Developers › API reference
Password Vault
Base address https://vault.kanishu.com/api/v1 · Download the OpenAPI description (for Postman, code generators and the like).
Conventions shared by every endpoint — tokens, headers, lists, safe retries, versions, limits — are in the developer guide; error codes are on Error codes. Each endpoint below names the scope a token needs.
Jump to: API access · People
API access
POST /api/v1/api-access-requests
Create in api access requests
Request fields (JSON body)
allowed_ips | string (up to 2000), can be null | |
api_client_id | integer, can be null | |
purpose required | string (up to 1000) | |
scopes required | list of string | |
validity_days | integer: 30, 60, 90, can be null |
201 — Created. The record is in `data`; its address in `Location`.
GET /api/v1/api-access-requests/pending
Pending (api access requests pending)
| Parameter | In | Type | About |
|---|---|---|---|
fields | query | string | Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back. |
200 — OK.
POST /api/v1/api-access-requests/{apiAccessRequest}/approve
Approve (api access requests approve)
| Parameter | In | Type | About |
|---|---|---|---|
apiAccessRequest required | path | integer |
200 — OK.
POST /api/v1/api-access-requests/{apiAccessRequest}/reject
Reject (api access requests reject)
| Parameter | In | Type | About |
|---|---|---|---|
apiAccessRequest required | path | integer |
Request fields (JSON body)
reason required | string (up to 500) |
200 — OK.
GET /api/v1/api-access-requests/{apiAccessRequest}/reveal
Reveal (api access requests reveal)
| Parameter | In | Type | About |
|---|---|---|---|
apiAccessRequest required | path | integer | |
fields | query | string | Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back. |
200 — OK.
Reply fields (1)
token | string | The API token, shown this once. Store it in your secrets manager and send it as Authorization: Bearer <token>. |
Need fewer? Add ?fields= with the names you want, e.g. ?fields=token.
People
GET /api/v1/people
List people · scope people:read
| Parameter | In | Type | About |
|---|---|---|---|
page | query | integer | Page number, from 1. |
per_page | query | integer | Items a page (default 25, at most 100). |
fields | query | string | Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back. |
200 — A page of results.
Reply fields (24) — each record in data
Also in the answer: meta, links.
id | string (uuid) | The person's id in People (a UUID). Use it with /people/{person}. |
display_name | string | The name shown everywhere in Kanishu. |
preferred_name | string, can be null | What they like to be called, if different. |
work_email | string | Their work email address; how they are matched to logins in the products. |
employee_number | string, can be null | Your own employee number for them (e.g. from payroll or HR). |
type | string | employee, contractor, external (auditor, consultant…) or other. |
status | string | pre_joining (joining soon), active, on_leave, leaving (last working day set) or left. |
joining_date | string (date), can be null | Their first working day. |
last_working_date | string (date), can be null | Their last working day, once they are leaving; their logins are switched off after it. |
access_end_date | string (date), can be null | When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors). |
department | object, can be null | Their department or team (id and name), from GET /people-organisation. |
department.id | string (uuid) | |
department.name | string | |
position | object, can be null | Their job position (id and name). |
position.id | string (uuid) | |
position.name | string | |
location | object, can be null | Their office or site (id and name). |
location.id | string (uuid) | |
location.name | string | |
manager | object, can be null | Their manager in People (id and display_name). |
manager.id | string (uuid) | |
manager.display_name | string | |
created_at | string (date and time, ISO 8601) | |
updated_at | string (date and time, ISO 8601) |
Need fewer? Add ?fields= with the names you want, e.g. ?fields=display_name,preferred_name.
POST /api/v1/people
Create in people · scope people:write
Request fields (JSON body)
access_end_date | string (date), can be null | When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors). |
display_name required | string (up to 255) | The name shown everywhere in Kanishu. |
employee_number | string (up to 50), can be null | Your own employee number for them (e.g. from payroll or HR). |
employment_status | string: pre_joining, active, on_leave, leaving, left | pre_joining (joining soon), active, on_leave, leaving (last working day set) or left. |
joining_date | string (date), can be null | Their first working day. |
location_id | string (uuid), can be null | |
manager_person_id | string (uuid), can be null | The manager's People id. |
org_unit_id | string (uuid), can be null | The department or team id, from GET /people-organisation. |
person_type | string: employee, contractor, external, other | employee, contractor, external (auditor, consultant…) or other. |
position_id | string (uuid), can be null | |
preferred_name | string (up to 255), can be null | What they like to be called, if different. |
work_email | string (email) (up to 255), can be null | Their work email address; how they are matched to logins in the products. |
201 — Created. The record is in `data`; its address in `Location`.
Reply fields (24) — in data
id | string (uuid) | The person's id in People (a UUID). Use it with /people/{person}. |
display_name | string | The name shown everywhere in Kanishu. |
preferred_name | string, can be null | What they like to be called, if different. |
work_email | string | Their work email address; how they are matched to logins in the products. |
employee_number | string, can be null | Your own employee number for them (e.g. from payroll or HR). |
type | string | employee, contractor, external (auditor, consultant…) or other. |
status | string | pre_joining (joining soon), active, on_leave, leaving (last working day set) or left. |
joining_date | string (date) | Their first working day. |
last_working_date | string (date), can be null | Their last working day, once they are leaving; their logins are switched off after it. |
access_end_date | string (date), can be null | When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors). |
department | object | Their department or team (id and name), from GET /people-organisation. |
department.id | string (uuid) | |
department.name | string | |
position | object | Their job position (id and name). |
position.id | string (uuid) | |
position.name | string | |
location | object | Their office or site (id and name). |
location.id | string (uuid) | |
location.name | string | |
manager | object, can be null | Their manager in People (id and display_name). |
manager.id | string (uuid) | |
manager.display_name | string | |
created_at | string (date and time, ISO 8601) | |
updated_at | string (date and time, ISO 8601) |
GET /api/v1/people-organisation
Organisation (people organisation) · scope people:read
| Parameter | In | Type | About |
|---|---|---|---|
fields | query | string | Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back. |
200 — OK. The record is in `data`, with its version in the `ETag` header.
Reply fields (18) — in data
departments | list | |
departments[].id | string (uuid) | |
departments[].name | string | |
departments[].type | string | What kind of unit it is (e.g. department, team, business unit). |
departments[].code | string | |
departments[].part_of_id | integer or string, can be null | The unit this one sits under, or null at the top. |
departments[].in_use | boolean | false when the unit is archived and no longer offered. |
positions | list | |
positions[].id | string (uuid) | |
positions[].name | string | |
positions[].code | string, can be null | |
positions[].in_use | boolean | false when the position is archived. |
locations | list | |
locations[].id | string (uuid) | |
locations[].name | string | |
locations[].code | string, can be null | |
locations[].city | string, can be null | |
locations[].in_use | boolean | false when the location is archived. |
Need fewer? Add ?fields= with the names you want, e.g. ?fields=departments,positions.
POST /api/v1/people/joiners
Add a joiner (from their start date) · scope people:write
Request fields (JSON body)
access | list of string, can be null | Logins they should get, as product key => role (e.g. {"itsm": "agent"}); each one waits for an approval. |
access_end_date | string (date), can be null | When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors). |
display_name required | string (up to 255) | The name shown everywhere in Kanishu. |
employee_number | string (up to 50), can be null | Your own employee number for them (e.g. from payroll or HR). |
employment_status | string: pre_joining, active, on_leave, leaving, left | pre_joining (joining soon), active, on_leave, leaving (last working day set) or left. |
joining_date | string (date), can be null | Their first working day. |
location_id | string (uuid), can be null | |
manager_person_id | string (uuid), can be null | The manager's People id. |
org_unit_id | string (uuid), can be null | The department or team id, from GET /people-organisation. |
person_type | string: employee, contractor, external, other | employee, contractor, external (auditor, consultant…) or other. |
position_id | string (uuid), can be null | |
preferred_name | string (up to 255), can be null | What they like to be called, if different. |
start_date required | string (date) | Their first working day; their logins are prepared for it. |
work_email | string (email) (up to 255), can be null | Their work email address; how they are matched to logins in the products. |
201 — The new person, as GET /people/{person} returns them.
Reply fields (24) — in data
id | string (uuid) | The person's id in People (a UUID). Use it with /people/{person}. |
display_name | string | The name shown everywhere in Kanishu. |
preferred_name | string, can be null | What they like to be called, if different. |
work_email | string | Their work email address; how they are matched to logins in the products. |
employee_number | string, can be null | Your own employee number for them (e.g. from payroll or HR). |
type | string | employee, contractor, external (auditor, consultant…) or other. |
status | string | pre_joining (joining soon), active, on_leave, leaving (last working day set) or left. |
joining_date | string (date) | Their first working day. |
last_working_date | string (date), can be null | Their last working day, once they are leaving; their logins are switched off after it. |
access_end_date | string (date), can be null | When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors). |
department | object | Their department or team (id and name), from GET /people-organisation. |
department.id | string (uuid) | |
department.name | string | |
position | object | Their job position (id and name). |
position.id | string (uuid) | |
position.name | string | |
location | object | Their office or site (id and name). |
location.id | string (uuid) | |
location.name | string | |
manager | object, can be null | Their manager in People (id and display_name). |
manager.id | string (uuid) | |
manager.display_name | string | |
created_at | string (date and time, ISO 8601) | |
updated_at | string (date and time, ISO 8601) |
GET /api/v1/people/{person}
Get one of people · scope people:read
| Parameter | In | Type | About |
|---|---|---|---|
person required | path | integer | |
fields | query | string | Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back. |
200 — OK. The record is in `data`, with its version in the `ETag` header.
Reply fields (24) — in data
id | string (uuid) | The person's id in People (a UUID). Use it with /people/{person}. |
display_name | string | The name shown everywhere in Kanishu. |
preferred_name | string, can be null | What they like to be called, if different. |
work_email | string | Their work email address; how they are matched to logins in the products. |
employee_number | string, can be null | Your own employee number for them (e.g. from payroll or HR). |
type | string | employee, contractor, external (auditor, consultant…) or other. |
status | string | pre_joining (joining soon), active, on_leave, leaving (last working day set) or left. |
joining_date | string (date) | Their first working day. |
last_working_date | string (date), can be null | Their last working day, once they are leaving; their logins are switched off after it. |
access_end_date | string (date), can be null | When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors). |
department | object | Their department or team (id and name), from GET /people-organisation. |
department.id | string (uuid) | |
department.name | string | |
position | object | Their job position (id and name). |
position.id | string (uuid) | |
position.name | string | |
location | object | Their office or site (id and name). |
location.id | string (uuid) | |
location.name | string | |
manager | object, can be null | Their manager in People (id and display_name). |
manager.id | string (uuid) | |
manager.display_name | string | |
created_at | string (date and time, ISO 8601) | |
updated_at | string (date and time, ISO 8601) |
Need fewer? Add ?fields= with the names you want, e.g. ?fields=display_name,preferred_name.
PATCH /api/v1/people/{person}
Change one of people · scope people:write
| Parameter | In | Type | About |
|---|---|---|---|
person required | path | integer |
Request fields (JSON body) — send only the fields you change
access_end_date | string (date), can be null | When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors). |
display_name | string (up to 255) | The name shown everywhere in Kanishu. |
employee_number | string (up to 50), can be null | Your own employee number for them (e.g. from payroll or HR). |
employment_status | string: pre_joining, active, on_leave, leaving, left | pre_joining (joining soon), active, on_leave, leaving (last working day set) or left. |
joining_date | string (date), can be null | Their first working day. |
location_id | string (uuid), can be null | |
manager_person_id | string (uuid), can be null | The manager's People id. |
org_unit_id | string (uuid), can be null | The department or team id, from GET /people-organisation. |
person_type | string: employee, contractor, external, other | employee, contractor, external (auditor, consultant…) or other. |
position_id | string (uuid), can be null | |
preferred_name | string (up to 255), can be null | What they like to be called, if different. |
work_email | string (email) (up to 255), can be null | Their work email address; how they are matched to logins in the products. |
200 — OK. The record is in `data`, with its version in the `ETag` header.
Reply fields (24) — in data
id | string (uuid) | The person's id in People (a UUID). Use it with /people/{person}. |
display_name | string | The name shown everywhere in Kanishu. |
preferred_name | string, can be null | What they like to be called, if different. |
work_email | string | Their work email address; how they are matched to logins in the products. |
employee_number | string, can be null | Your own employee number for them (e.g. from payroll or HR). |
type | string | employee, contractor, external (auditor, consultant…) or other. |
status | string | pre_joining (joining soon), active, on_leave, leaving (last working day set) or left. |
joining_date | string (date) | Their first working day. |
last_working_date | string (date), can be null | Their last working day, once they are leaving; their logins are switched off after it. |
access_end_date | string (date), can be null | When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors). |
department | object | Their department or team (id and name), from GET /people-organisation. |
department.id | string (uuid) | |
department.name | string | |
position | object | Their job position (id and name). |
position.id | string (uuid) | |
position.name | string | |
location | object | Their office or site (id and name). |
location.id | string (uuid) | |
location.name | string | |
manager | object, can be null | Their manager in People (id and display_name). |
manager.id | string (uuid) | |
manager.display_name | string | |
created_at | string (date and time, ISO 8601) | |
updated_at | string (date and time, ISO 8601) |
POST /api/v1/people/{person}/leave
Record a leaver (logins switched off after the last working day, or now if urgent) · scope people:write
| Parameter | In | Type | About |
|---|---|---|---|
person required | path | integer |
Request fields (JSON body)
last_working_date required | string (date) | Their last working day, once they are leaving; their logins are switched off after it. |
reason | string (up to 500), can be null | Why they are leaving (kept in People's History). |
urgent | boolean | true to switch their logins off now instead of after the last working day. |
200 — The person, as GET /people/{person} returns them.
Reply fields (24) — in data
id | string (uuid) | The person's id in People (a UUID). Use it with /people/{person}. |
display_name | string | The name shown everywhere in Kanishu. |
preferred_name | string, can be null | What they like to be called, if different. |
work_email | string | Their work email address; how they are matched to logins in the products. |
employee_number | string, can be null | Your own employee number for them (e.g. from payroll or HR). |
type | string | employee, contractor, external (auditor, consultant…) or other. |
status | string | pre_joining (joining soon), active, on_leave, leaving (last working day set) or left. |
joining_date | string (date) | Their first working day. |
last_working_date | string (date), can be null | Their last working day, once they are leaving; their logins are switched off after it. |
access_end_date | string (date), can be null | When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors). |
department | object | Their department or team (id and name), from GET /people-organisation. |
department.id | string (uuid) | |
department.name | string | |
position | object | Their job position (id and name). |
position.id | string (uuid) | |
position.name | string | |
location | object | Their office or site (id and name). |
location.id | string (uuid) | |
location.name | string | |
manager | object, can be null | Their manager in People (id and display_name). |
manager.id | string (uuid) | |
manager.display_name | string | |
created_at | string (date and time, ISO 8601) | |
updated_at | string (date and time, ISO 8601) |
POST /api/v1/people/{person}/move
Move a person (department, manager, position or location) from a date · scope people:write
| Parameter | In | Type | About |
|---|---|---|---|
person required | path | integer |
Request fields (JSON body)
department_id | string (uuid), can be null | The department or team they move to, from GET /people-organisation. |
effective_date required | string (date) | The date the move takes effect. |
location_id | string (uuid), can be null | |
manager_id | string (uuid), can be null | Their new manager's People id. |
position_id | string (uuid), can be null |
200 — The person, as GET /people/{person} returns them.
Reply fields (24) — in data
id | string (uuid) | The person's id in People (a UUID). Use it with /people/{person}. |
display_name | string | The name shown everywhere in Kanishu. |
preferred_name | string, can be null | What they like to be called, if different. |
work_email | string | Their work email address; how they are matched to logins in the products. |
employee_number | string, can be null | Your own employee number for them (e.g. from payroll or HR). |
type | string | employee, contractor, external (auditor, consultant…) or other. |
status | string | pre_joining (joining soon), active, on_leave, leaving (last working day set) or left. |
joining_date | string (date) | Their first working day. |
last_working_date | string (date), can be null | Their last working day, once they are leaving; their logins are switched off after it. |
access_end_date | string (date), can be null | When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors). |
department | object | Their department or team (id and name), from GET /people-organisation. |
department.id | string (uuid) | |
department.name | string | |
position | object | Their job position (id and name). |
position.id | string (uuid) | |
position.name | string | |
location | object | Their office or site (id and name). |
location.id | string (uuid) | |
location.name | string | |
manager | object, can be null | Their manager in People (id and display_name). |
manager.id | string (uuid) | |
manager.display_name | string | |
created_at | string (date and time, ISO 8601) | |
updated_at | string (date and time, ISO 8601) |