{ "openapi": "3.1.0", "info": { "title": "Kanishu Policy 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://policy.kanishu.com/api/v1" } ], "security": [ { "bearer": [] } ], "paths": { "/acknowledgements": { "get": { "operationId": "getAcknowledgementsStatus", "summary": "Status (acknowledgements)", "tags": [ "Acknowledgements" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "email", "in": "query", "required": true, "schema": { "type": "string", "format": "email", "maxLength": 255 }, "description": "" }, { "name": "policy_ids", "in": "query", "required": true, "schema": { "type": "array", "items": {}, "maxItems": 50 }, "description": "" }, { "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" } }, "description": "Needs the `acknowledgements:request` scope. Used between Kanishu products; not offered to customers.", "x-scope": "acknowledgements:request", "x-internal": true }, "post": { "operationId": "postAcknowledgementsStore", "summary": "Create in acknowledgements", "tags": [ "Acknowledgements" ], "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" } }, "description": "Needs the `acknowledgements:request` scope. Used between Kanishu products; not offered to customers.", "x-scope": "acknowledgements:request", "x-internal": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 255 }, "name": { "type": "string", "nullable": true, "maxLength": 255 }, "policy_ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1, "maxItems": 50 }, "reason": { "type": "string", "nullable": true, "maxLength": 200 } }, "required": [ "email", "policy_ids" ] } } } } } }, "/acknowledgements/policies": { "get": { "operationId": "getAcknowledgementsPoliciesPolicies", "summary": "Policies (acknowledgements policies)", "tags": [ "Acknowledgements" ], "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": { "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "version": { "type": "string" } } }, "type": "array" } } } } } }, "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 `acknowledgements:request` scope. Used between Kanishu products; not offered to customers.", "x-scope": "acknowledgements:request", "x-internal": true } }, "/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": [ "people:read", "people:write", "policies:read", "reads:write", "reads:read", "controls:read" ] }, "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" } } } }, "/controls/audit-feed": { "get": { "operationId": "getControlsAuditFeedCoverageFeed", "summary": "Coverage Feed (controls audit feed)", "tags": [ "Controls" ], "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": { "items": { "type": "object", "properties": { "framework": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" } } }, "summary": { "type": "object", "properties": { "controls": { "type": "integer" }, "covered": { "type": "integer" }, "gaps": { "type": "integer" } } }, "gaps": { "type": "array", "items": { "type": "object", "properties": { "control_ref": { "type": "string" }, "title": { "type": "string" } } } }, "covered": { "type": "array", "items": { "type": "object", "properties": { "control_ref": { "type": "string" }, "title": { "type": "string" }, "policies": { "type": "array", "items": { "type": "string" } } } } } } }, "type": "array" }, "meta": { "type": "object", "properties": { "regulation_mapping": { "type": "boolean" } } } } } } } }, "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 `controls:audit-read` scope. Used between Kanishu products; not offered to customers.", "x-scope": "controls:audit-read", "x-internal": true } }, "/controls/coverage": { "get": { "operationId": "getControlsCoverageIndex", "summary": "Which controls of a framework your published policies cover", "tags": [ "Controls" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "framework", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "iso27001_2022", "soc2_tsc", "dpdp_2023", "gdpr" ] }, "description": "One of: `iso27001_2022` (ISO/IEC 27001:2022 Annex A), `soc2_tsc` (SOC 2 Trust Services Criteria), `dpdp_2023` (India Digital Personal Data Protection Act, 2023), `gdpr` (EU General Data Protection Regulation)." }, { "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": "The whole framework in one answer (no paging). Business and Enterprise plans.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "framework": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" } } }, "summary": { "type": "object", "properties": { "controls": { "type": "integer" }, "covered": { "type": "integer" }, "gaps": { "type": "integer" } } }, "controls": { "type": "array", "items": { "type": "object" } } } } } } } } }, "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 `controls:read` scope.", "x-scope": "controls:read" } }, "/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.", "x-scope": "people:read" }, "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.", "x-scope": "people:write", "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.", "x-scope": "people:read" } }, "/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.", "x-scope": "people:write", "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.", "x-scope": "people:read" }, "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.", "x-scope": "people:write", "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.", "x-scope": "people:write", "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.", "x-scope": "people:write", "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" ] } } } } } }, "/policies": { "get": { "operationId": "getPoliciesIndex", "summary": "List policies", "tags": [ "Policies" ], "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." }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Related records in the same answer, comma-separated: `controls` — The framework controls the policy supports: framework, control_ref, title, rationale (why it supports it), reviewed_at (when an approver signed the mapping off, or null) (needs `controls:read`)." } ], "responses": { "200": { "description": "Every matching record in one answer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "category": { "type": "string", "description": "The policy's category (e.g. IT_SECURITY)." }, "version_label": { "type": "string", "description": "The published version (e.g. 1.0)." }, "published_at": { "type": "string", "format": "date-time", "description": "When this version was published." }, "content_hash": { "type": "string", "description": "SHA-256 of the published text: if it changes, the policy changed." }, "controls": { "type": "array", "items": { "type": "object", "properties": { "framework": { "type": "string", "description": "The framework key (iso27001_2022, soc2_tsc, dpdp_2023, gdpr)." }, "control_ref": { "type": "string", "description": "The control's reference in that framework (e.g. A.5.1)." }, "title": { "type": "string" }, "rationale": { "type": [ "string", "null" ], "description": "Why the policy supports the control, if recorded." }, "reviewed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When an approver signed the mapping off, or null." } } }, "description": "Only with ?include=controls. The framework controls the policy supports: framework, control_ref, title, rationale (why it supports it), reviewed_at (when an approver signed the mapping off, or null)." } } }, "type": "array" } } } } } }, "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 `policies:read` scope.", "x-scope": "policies:read" } }, "/policies/{policy}": { "get": { "operationId": "getPoliciesShow", "summary": "Get one of policies", "tags": [ "Policies" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "policy", "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." }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Related records in the same answer, comma-separated: `controls` — The framework controls the policy supports: framework, control_ref, title, rationale (why it supports it), reviewed_at (when an approver signed the mapping off, or null) (needs `controls:read`)." } ], "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": "integer" }, "title": { "type": "string" }, "category": { "type": "string", "description": "The policy's category (e.g. IT_SECURITY)." }, "version_label": { "type": "string", "description": "The published version (e.g. 1.0)." }, "published_at": { "type": "string", "format": "date-time", "description": "When this version was published." }, "content_hash": { "type": "string", "description": "SHA-256 of the published text: if it changes, the policy changed." }, "sections": { "type": "object", "properties": { "purpose": { "type": "string" }, "scope": { "type": "string" }, "statements": { "type": "array", "items": { "type": "string" } }, "responsibilities": { "type": "array", "items": { "type": "string" } }, "related": { "type": "string" } }, "description": "The policy text by section: purpose, scope, statements, responsibilities and related documents." }, "controls": { "type": "array", "items": {}, "description": "Only with ?include=controls. The framework controls the policy supports: framework, control_ref, title, rationale (why it supports it), reviewed_at (when an approver signed the mapping off, or null)." } } } } } } } }, "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 `policies:read` scope.", "x-scope": "policies:read" } }, "/read-events": { "get": { "operationId": "getReadEventsIndex", "summary": "Who opened and who accepted each policy", "tags": [ "Read" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "name": "since_id", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Return events after this id: pass the next_since_id from your last call. Start with 0." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "description": "At most this many events (default 200, at most 500)." }, { "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." }, { "name": "include", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Related records in the same answer, comma-separated: `policy` — The policy the event is about: id, title, category (needs `policies:read`)." } ], "responses": { "200": { "description": "Events oldest first, one OPENED and one ACCEPTED at most per person and version. An empty list means you are up to date; keep next_since_id for the next call. People who have not read a policy are never listed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "policy_id": { "type": "integer" }, "version_label": { "type": "string", "description": "The policy version the person read." }, "employee_ref": { "type": "string", "description": "Your own id for the person, as you sent it when creating the read link." }, "employee_name": { "type": [ "string", "null" ] }, "event": { "type": "string", "enum": [ "OPENED", "ACCEPTED" ], "description": "OPENED (the person opened the policy) or ACCEPTED (they clicked to accept it)." }, "integration": { "type": [ "string", "null" ], "description": "Which token or screen sent the link." }, "occurred_at": { "type": "string", "format": "date-time", "description": "When it happened." } } } }, "next_since_id": { "type": "integer" } } } } } }, "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 `reads:read` scope.", "x-scope": "reads:read" } }, "/read-sessions": { "post": { "operationId": "postReadSessionsStore", "summary": "Send a person a policy to read and accept", "tags": [ "Read" ], "parameters": [ { "$ref": "#/components/parameters/RequestId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "A link to open in the person's browser. It is for that person only, pinned to the version published now, and expires after 30 minutes. The person reads the policy and clicks to accept; both show up in GET /read-events.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "The link to open in the person's browser (for that person only)." }, "expires_at": { "type": "string", "format": "date-time", "description": "When the link stops working." } } } } } }, "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 `reads:write` scope.", "x-scope": "reads:write", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "policy_id": { "type": "integer", "description": "A published policy (GET /policies)." }, "employee_ref": { "type": "string", "maxLength": 255, "description": "Your own id for the person (employee number, email…). It comes back in the read-events feed." }, "employee_name": { "type": "string", "maxLength": 255, "description": "Shown to the person and in the records. Optional." } }, "required": [ "policy_id", "employee_ref" ] } } } } } } }, "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" } } } } } } }