{ "openapi": "3.1.0", "info": { "title": "Kanishu Assurance API", "version": "v1", "description": "Generated from the product's routes (suite/api-kit). Conventions — lists, values, versions, retries, limits — are in the Kanishu API standard; every error uses the envelope below, with the codes in \"API errors\"." }, "servers": [ { "url": "https://assurance.kanishu.com/api/v1" } ], "security": [ { "bearer": [] } ], "paths": { "/api-access-requests": { "post": { "operationId": "postApiAccessRequestsStore", "summary": "Create in api access requests", "tags": [ "Api" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Created. The record is in `data`; its address in `Location`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "allowed_ips": { "type": "string", "nullable": true, "maxLength": 2000 }, "api_client_id": { "type": "integer", "nullable": true }, "purpose": { "type": "string", "maxLength": 1000 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "" ] }, "minItems": 1 }, "validity_days": { "type": "integer", "nullable": true, "enum": [ "30", "60", "90" ] } }, "required": [ "purpose", "scopes" ] } } } } } }, "/api-access-requests/pending": { "get": { "operationId": "getApiAccessRequestsPendingPending", "summary": "Pending (api access requests pending)", "tags": [ "Api" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/api-access-requests/{apiAccessRequest}/approve": { "post": { "operationId": "postApiAccessRequestsApproveApprove", "summary": "Approve (api access requests approve)", "tags": [ "Api" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "apiAccessRequest", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/api-access-requests/{apiAccessRequest}/reject": { "post": { "operationId": "postApiAccessRequestsRejectReject", "summary": "Reject (api access requests reject)", "tags": [ "Api" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "apiAccessRequest", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": {} } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "maxLength": 500 } }, "required": [ "reason" ] } } } } } }, "/api-access-requests/{apiAccessRequest}/reveal": { "get": { "operationId": "getApiAccessRequestsRevealReveal", "summary": "Reveal (api access requests reveal)", "tags": [ "Api" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "apiAccessRequest", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "The API token, shown this once. Store it in your secrets manager and send it as Authorization: Bearer ." } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } } } }, "/people": { "get": { "operationId": "getPeopleIndex", "summary": "List people", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "Page number, from 1." }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "Items a page (default 25, at most 100)." }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." } ], "responses": { "200": { "description": "A page of results.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": [ "string", "null" ], "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "type": "array" }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" }, "current_page": { "type": "integer" } } }, "links": { "type": "object", "properties": { "first": { "type": "string" }, "prev": { "type": [ "string", "null" ], "format": "uri" }, "next": { "type": [ "string", "null" ], "format": "uri" }, "last": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:read` scope. Used between Kanishu products; not offered to customers.", "x-scope": "people:read", "x-internal": true }, "post": { "operationId": "postPeopleStore", "summary": "Create in people", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "Created. The record is in `data`; its address in `Location`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:write` scope. Used between Kanishu products; not offered to customers.", "x-scope": "people:write", "x-internal": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "access_end_date": { "type": "string", "nullable": true, "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "display_name": { "type": "string", "maxLength": 255, "description": "The name shown everywhere in Kanishu." }, "employee_number": { "type": "string", "nullable": true, "maxLength": 50, "description": "Your own employee number for them (e.g. from payroll or HR)." }, "employment_status": { "type": "string", "enum": [ "pre_joining", "active", "on_leave", "leaving", "left" ], "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "nullable": true, "format": "date", "description": "Their first working day." }, "location_id": { "type": "string", "nullable": true, "format": "uuid" }, "manager_person_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The manager's People id." }, "org_unit_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The department or team id, from GET /people-organisation." }, "person_type": { "type": "string", "enum": [ "employee", "contractor", "external", "other" ], "description": "employee, contractor, external (auditor, consultant…) or other." }, "position_id": { "type": "string", "nullable": true, "format": "uuid" }, "preferred_name": { "type": "string", "nullable": true, "maxLength": 255, "description": "What they like to be called, if different." }, "work_email": { "type": "string", "nullable": true, "format": "email", "maxLength": 255, "description": "Their work email address; how they are matched to logins in the products." } }, "required": [ "display_name" ] } } } } } }, "/people-organisation": { "get": { "operationId": "getPeopleOrganisationOrganisation", "summary": "Organisation (people organisation)", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." } ], "responses": { "200": { "description": "OK. The record is in `data`, with its version in the `ETag` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "departments": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "description": "What kind of unit it is (e.g. department, team, business unit)." }, "code": { "type": "string" }, "part_of_id": { "type": [ "integer", "string", "null" ], "description": "The unit this one sits under, or null at the top." }, "in_use": { "type": "boolean", "description": "false when the unit is archived and no longer offered." } } } }, "positions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "in_use": { "type": "boolean", "description": "false when the position is archived." } } } }, "locations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "code": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "in_use": { "type": "boolean", "description": "false when the location is archived." } } } } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:read` scope. Used between Kanishu products; not offered to customers.", "x-scope": "people:read", "x-internal": true } }, "/people/joiners": { "post": { "operationId": "postPeopleJoinersJoin", "summary": "Add a joiner (from their start date)", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "The new person, as GET /people/{person} returns them.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:write` scope. Used between Kanishu products; not offered to customers.", "x-scope": "people:write", "x-internal": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "access": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "nullable": true, "description": "Logins they should get, as product key => role (e.g. {\"itsm\": \"agent\"}); each one waits for an approval." }, "access_end_date": { "type": "string", "nullable": true, "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "display_name": { "type": "string", "maxLength": 255, "description": "The name shown everywhere in Kanishu." }, "employee_number": { "type": "string", "nullable": true, "maxLength": 50, "description": "Your own employee number for them (e.g. from payroll or HR)." }, "employment_status": { "type": "string", "enum": [ "pre_joining", "active", "on_leave", "leaving", "left" ], "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "nullable": true, "format": "date", "description": "Their first working day." }, "location_id": { "type": "string", "nullable": true, "format": "uuid" }, "manager_person_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The manager's People id." }, "org_unit_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The department or team id, from GET /people-organisation." }, "person_type": { "type": "string", "enum": [ "employee", "contractor", "external", "other" ], "description": "employee, contractor, external (auditor, consultant…) or other." }, "position_id": { "type": "string", "nullable": true, "format": "uuid" }, "preferred_name": { "type": "string", "nullable": true, "maxLength": 255, "description": "What they like to be called, if different." }, "start_date": { "type": "string", "format": "date", "description": "Their first working day; their logins are prepared for it." }, "work_email": { "type": "string", "nullable": true, "format": "email", "maxLength": 255, "description": "Their work email address; how they are matched to logins in the products." } }, "required": [ "display_name", "start_date" ] } } } } } }, "/people/{person}": { "get": { "operationId": "getPeopleShow", "summary": "Get one of people", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "person", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "fields", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back." } ], "responses": { "200": { "description": "OK. The record is in `data`, with its version in the `ETag` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "400": { "$ref": "#/components/responses/E400" }, "401": { "$ref": "#/components/responses/E401" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:read` scope. Used between Kanishu products; not offered to customers.", "x-scope": "people:read", "x-internal": true }, "patch": { "operationId": "patchPeopleUpdate", "summary": "Change one of people", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "person", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IfMatch" } ], "responses": { "200": { "description": "OK. The record is in `data`, with its version in the `ETag` header.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "412": { "$ref": "#/components/responses/E412" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:write` scope. Used between Kanishu products; not offered to customers.", "x-scope": "people:write", "x-internal": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "access_end_date": { "type": "string", "nullable": true, "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "display_name": { "type": "string", "maxLength": 255, "description": "The name shown everywhere in Kanishu." }, "employee_number": { "type": "string", "nullable": true, "maxLength": 50, "description": "Your own employee number for them (e.g. from payroll or HR)." }, "employment_status": { "type": "string", "enum": [ "pre_joining", "active", "on_leave", "leaving", "left" ], "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "nullable": true, "format": "date", "description": "Their first working day." }, "location_id": { "type": "string", "nullable": true, "format": "uuid" }, "manager_person_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The manager's People id." }, "org_unit_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The department or team id, from GET /people-organisation." }, "person_type": { "type": "string", "enum": [ "employee", "contractor", "external", "other" ], "description": "employee, contractor, external (auditor, consultant…) or other." }, "position_id": { "type": "string", "nullable": true, "format": "uuid" }, "preferred_name": { "type": "string", "nullable": true, "maxLength": 255, "description": "What they like to be called, if different." }, "work_email": { "type": "string", "nullable": true, "format": "email", "maxLength": 255, "description": "Their work email address; how they are matched to logins in the products." } } } } } } } }, "/people/{person}/leave": { "post": { "operationId": "postPeopleLeaveLeave", "summary": "Record a leaver (logins switched off after the last working day, or now if urgent)", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "person", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The person, as GET /people/{person} returns them.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:write` scope. Used between Kanishu products; not offered to customers.", "x-scope": "people:write", "x-internal": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "last_working_date": { "type": "string", "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "reason": { "type": "string", "nullable": true, "maxLength": 500, "description": "Why they are leaving (kept in People's History)." }, "urgent": { "type": "boolean", "description": "true to switch their logins off now instead of after the last working day." } }, "required": [ "last_working_date" ] } } } } } }, "/people/{person}/move": { "post": { "operationId": "postPeopleMoveMove", "summary": "Move a person (department, manager, position or location) from a date", "tags": [ "People" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "person", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The person, as GET /people/{person} returns them.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The person's id in People (a UUID). Use it with /people/{person}." }, "display_name": { "type": "string", "description": "The name shown everywhere in Kanishu." }, "preferred_name": { "type": [ "string", "null" ], "description": "What they like to be called, if different." }, "work_email": { "type": "string", "description": "Their work email address; how they are matched to logins in the products." }, "employee_number": { "type": [ "string", "null" ], "description": "Your own employee number for them (e.g. from payroll or HR)." }, "type": { "type": "string", "description": "employee, contractor, external (auditor, consultant…) or other." }, "status": { "type": "string", "description": "pre_joining (joining soon), active, on_leave, leaving (last working day set) or left." }, "joining_date": { "type": "string", "format": "date", "description": "Their first working day." }, "last_working_date": { "type": [ "string", "null" ], "format": "date", "description": "Their last working day, once they are leaving; their logins are switched off after it." }, "access_end_date": { "type": [ "string", "null" ], "format": "date", "description": "When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors)." }, "department": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their department or team (id and name), from GET /people-organisation." }, "position": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their job position (id and name)." }, "location": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } }, "description": "Their office or site (id and name)." }, "manager": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "format": "uuid" }, "display_name": { "type": "string" } }, "description": "Their manager in People (id and display_name)." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "$ref": "#/components/responses/E401" }, "402": { "$ref": "#/components/responses/E402" }, "403": { "$ref": "#/components/responses/E403" }, "404": { "$ref": "#/components/responses/E404" }, "409": { "$ref": "#/components/responses/E409" }, "422": { "$ref": "#/components/responses/E422" }, "429": { "$ref": "#/components/responses/E429" }, "500": { "$ref": "#/components/responses/E500" }, "503": { "$ref": "#/components/responses/E503" } }, "description": "Needs the `people:write` scope. Used between Kanishu products; not offered to customers.", "x-scope": "people:write", "x-internal": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "department_id": { "type": "string", "nullable": true, "format": "uuid", "description": "The department or team they move to, from GET /people-organisation." }, "effective_date": { "type": "string", "format": "date", "description": "The date the move takes effect." }, "location_id": { "type": "string", "nullable": true, "format": "uuid" }, "manager_id": { "type": "string", "nullable": true, "format": "uuid", "description": "Their new manager's People id." }, "position_id": { "type": "string", "nullable": true, "format": "uuid" } }, "required": [ "effective_date" ] } } } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "A token from API Access in the product. Never put it in a URL." } }, "parameters": { "RequestId": { "name": "X-Request-Id", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{1,64}$" }, "description": "Your id for this call; echoed back. Generated when absent." }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^[A-Za-z0-9-]{8,100}$" }, "description": "Makes a POST safe to retry: the first answer is kept for 24 hours." }, "IfMatch": { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string" }, "description": "The ETag you read. The change is refused with 412 version_conflict if the record changed since." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "details", "request_id" ], "properties": { "code": { "type": "string", "enum": [ "unauthenticated", "invalid_token", "bad_signature", "token_in_url", "session_expired", "ip_not_allowed", "invalid_scope", "forbidden", "forbidden_organization", "not_supported", "feature_not_included", "subscription_read_only", "subscription_suspended", "limit_reached", "rate_limited", "quota_exceeded", "daily_limit_exceeded", "bad_request", "invalid_request", "request_failed", "validation_failed", "missing_organization_id", "not_eligible", "approval_refused", "incomplete", "activation_failed", "idempotency_key_reused", "idempotency_in_progress", "invalid_filter", "invalid_sort", "invalid_include", "invalid_fields", "not_found", "method_not_allowed", "conflict", "duplicate", "exists", "version_conflict", "payload_too_large", "unsupported_media_type", "product_maintenance", "product_disabled", "platform_tenant_not_configured", "unavailable", "server_error" ] }, "message": { "type": "string" }, "details": { "type": "object" }, "request_id": { "type": "string" } } } } }, "ListMeta": { "type": "object", "properties": { "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } } } }, "responses": { "E400": { "description": "Bad request (invalid_filter, invalid_sort, invalid_fields, bad_request).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E401": { "description": "No or bad token (unauthenticated, invalid_token).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E402": { "description": "Plan limit or feature (limit_reached, feature_not_included).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E403": { "description": "Not allowed (invalid_scope, forbidden, forbidden_organization, ip_not_allowed).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E409": { "description": "Conflict (duplicate, idempotency_key_reused, idempotency_in_progress).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E412": { "description": "The record changed since you read it (version_conflict).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E422": { "description": "Validation failed; details.fields lists each field.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E429": { "description": "Too many calls (rate_limited, daily quota). See Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E500": { "description": "Server error. Quote request_id to support.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "E503": { "description": "Unavailable (maintenance).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }