Developers › API reference
Policy Management
Base address https://policy.kanishu.com/api/v1 · Download the OpenAPI description (for Postman, code generators and the like).
Conventions shared by every endpoint — tokens, headers, lists, safe retries, versions, limits — are in the developer guide; error codes are on Error codes. Each endpoint below names the scope a token needs.
Jump to: API access · Acknowledgements · Controls · People · Policies · Read
API access
POST /api/v1/api-access-requests
Create in api access requests
Request fields (JSON body)
allowed_ips | string (up to 2000), can be null | |
api_client_id | integer, can be null | |
purpose required | string (up to 1000) | |
scopes required | list of string | |
validity_days | integer: 30, 60, 90, can be null |
201 — Created. The record is in `data`; its address in `Location`.
GET /api/v1/api-access-requests/pending
Pending (api access requests pending)
| Parameter | In | Type | About |
|---|---|---|---|
fields | query | string | Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back. |
200 — OK.
POST /api/v1/api-access-requests/{apiAccessRequest}/approve
Approve (api access requests approve)
| Parameter | In | Type | About |
|---|---|---|---|
apiAccessRequest required | path | integer |
200 — OK.
POST /api/v1/api-access-requests/{apiAccessRequest}/reject
Reject (api access requests reject)
| Parameter | In | Type | About |
|---|---|---|---|
apiAccessRequest required | path | integer |
Request fields (JSON body)
reason required | string (up to 500) |
200 — OK.
GET /api/v1/api-access-requests/{apiAccessRequest}/reveal
Reveal (api access requests reveal)
| Parameter | In | Type | About |
|---|---|---|---|
apiAccessRequest required | path | integer | |
fields | query | string | Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back. |
200 — OK.
Reply fields (1)
token | string | The API token, shown this once. Store it in your secrets manager and send it as Authorization: Bearer <token>. |
Need fewer? Add ?fields= with the names you want, e.g. ?fields=token.
Acknowledgements
GET /api/v1/acknowledgements
Status (acknowledgements) · scope acknowledgements:request
| Parameter | In | Type | About |
|---|---|---|---|
email required | query | string | |
policy_ids required | query | array | |
fields | query | string | Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back. |
200 — OK.
POST /api/v1/acknowledgements
Create in acknowledgements · scope acknowledgements:request
Request fields (JSON body)
email required | string (email) (up to 255) | |
name | string (up to 255), can be null | |
policy_ids required | list of integer | |
reason | string (up to 200), can be null |
201 — Created. The record is in `data`; its address in `Location`.
GET /api/v1/acknowledgements/policies
Policies (acknowledgements policies) · scope acknowledgements:request
| Parameter | In | Type | About |
|---|---|---|---|
fields | query | string | Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back. |
200 — OK.
Reply fields (3) — each record in data
id | integer |
title | string |
version | string |
Need fewer? Add ?fields= with the names you want, e.g. ?fields=title,version.
Controls
GET /api/v1/controls/audit-feed
Coverage Feed (controls audit feed) · scope controls:audit-read
| Parameter | In | Type | About |
|---|---|---|---|
fields | query | string | Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back. |
200 — OK.
Reply fields (14) — each record in data
Also in the answer: meta.
framework | object |
framework.key | string |
framework.name | string |
summary | object |
summary.controls | integer |
summary.covered | integer |
summary.gaps | integer |
gaps | list |
gaps[].control_ref | string |
gaps[].title | string |
covered | list |
covered[].control_ref | string |
covered[].title | string |
covered[].policies | list of string |
Need fewer? Add ?fields= with the names you want, e.g. ?fields=framework,summary.
GET /api/v1/controls/coverage
Which controls of a framework your published policies cover · scope controls:read
| Parameter | In | Type | About |
|---|---|---|---|
framework required | query | string: iso27001_2022, soc2_tsc, dpdp_2023, gdpr | 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). |
fields | query | string | Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back. |
200 — The whole framework in one answer (no paging). Business and Enterprise plans.
Reply fields (8) — in data
framework | object |
framework.key | string |
framework.name | string |
summary | object |
summary.controls | integer |
summary.covered | integer |
summary.gaps | integer |
controls | list |
Need fewer? Add ?fields= with the names you want, e.g. ?fields=framework,summary.
People
GET /api/v1/people
List people · scope people:read
| Parameter | In | Type | About |
|---|---|---|---|
page | query | integer | Page number, from 1. |
per_page | query | integer | Items a page (default 25, at most 100). |
fields | query | string | Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back. |
200 — A page of results.
Reply fields (24) — each record in data
Also in the answer: meta, links.
id | string (uuid) | The person's id in People (a UUID). Use it with /people/{person}. |
display_name | string | The name shown everywhere in Kanishu. |
preferred_name | string, can be null | What they like to be called, if different. |
work_email | string | Their work email address; how they are matched to logins in the products. |
employee_number | string, can be null | Your own employee number for them (e.g. from payroll or HR). |
type | string | employee, contractor, external (auditor, consultant…) or other. |
status | string | pre_joining (joining soon), active, on_leave, leaving (last working day set) or left. |
joining_date | string (date), can be null | Their first working day. |
last_working_date | string (date), can be null | Their last working day, once they are leaving; their logins are switched off after it. |
access_end_date | string (date), can be null | When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors). |
department | object, can be null | Their department or team (id and name), from GET /people-organisation. |
department.id | string (uuid) | |
department.name | string | |
position | object, can be null | Their job position (id and name). |
position.id | string (uuid) | |
position.name | string | |
location | object, can be null | Their office or site (id and name). |
location.id | string (uuid) | |
location.name | string | |
manager | object, can be null | Their manager in People (id and display_name). |
manager.id | string (uuid) | |
manager.display_name | string | |
created_at | string (date and time, ISO 8601) | |
updated_at | string (date and time, ISO 8601) |
Need fewer? Add ?fields= with the names you want, e.g. ?fields=display_name,preferred_name.
POST /api/v1/people
Create in people · scope people:write
Request fields (JSON body)
access_end_date | string (date), can be null | When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors). |
display_name required | string (up to 255) | The name shown everywhere in Kanishu. |
employee_number | string (up to 50), can be null | Your own employee number for them (e.g. from payroll or HR). |
employment_status | string: pre_joining, active, on_leave, leaving, left | pre_joining (joining soon), active, on_leave, leaving (last working day set) or left. |
joining_date | string (date), can be null | Their first working day. |
location_id | string (uuid), can be null | |
manager_person_id | string (uuid), can be null | The manager's People id. |
org_unit_id | string (uuid), can be null | The department or team id, from GET /people-organisation. |
person_type | string: employee, contractor, external, other | employee, contractor, external (auditor, consultant…) or other. |
position_id | string (uuid), can be null | |
preferred_name | string (up to 255), can be null | What they like to be called, if different. |
work_email | string (email) (up to 255), can be null | Their work email address; how they are matched to logins in the products. |
201 — Created. The record is in `data`; its address in `Location`.
Reply fields (24) — in data
id | string (uuid) | The person's id in People (a UUID). Use it with /people/{person}. |
display_name | string | The name shown everywhere in Kanishu. |
preferred_name | string, can be null | What they like to be called, if different. |
work_email | string | Their work email address; how they are matched to logins in the products. |
employee_number | string, can be null | Your own employee number for them (e.g. from payroll or HR). |
type | string | employee, contractor, external (auditor, consultant…) or other. |
status | string | pre_joining (joining soon), active, on_leave, leaving (last working day set) or left. |
joining_date | string (date) | Their first working day. |
last_working_date | string (date), can be null | Their last working day, once they are leaving; their logins are switched off after it. |
access_end_date | string (date), can be null | When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors). |
department | object | Their department or team (id and name), from GET /people-organisation. |
department.id | string (uuid) | |
department.name | string | |
position | object | Their job position (id and name). |
position.id | string (uuid) | |
position.name | string | |
location | object | Their office or site (id and name). |
location.id | string (uuid) | |
location.name | string | |
manager | object, can be null | Their manager in People (id and display_name). |
manager.id | string (uuid) | |
manager.display_name | string | |
created_at | string (date and time, ISO 8601) | |
updated_at | string (date and time, ISO 8601) |
GET /api/v1/people-organisation
Organisation (people organisation) · scope people:read
| Parameter | In | Type | About |
|---|---|---|---|
fields | query | string | Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back. |
200 — OK. The record is in `data`, with its version in the `ETag` header.
Reply fields (18) — in data
departments | list | |
departments[].id | string (uuid) | |
departments[].name | string | |
departments[].type | string | What kind of unit it is (e.g. department, team, business unit). |
departments[].code | string | |
departments[].part_of_id | integer or string, can be null | The unit this one sits under, or null at the top. |
departments[].in_use | boolean | false when the unit is archived and no longer offered. |
positions | list | |
positions[].id | string (uuid) | |
positions[].name | string | |
positions[].code | string, can be null | |
positions[].in_use | boolean | false when the position is archived. |
locations | list | |
locations[].id | string (uuid) | |
locations[].name | string | |
locations[].code | string, can be null | |
locations[].city | string, can be null | |
locations[].in_use | boolean | false when the location is archived. |
Need fewer? Add ?fields= with the names you want, e.g. ?fields=departments,positions.
POST /api/v1/people/joiners
Add a joiner (from their start date) · scope people:write
Request fields (JSON body)
access | list of string, can be null | Logins they should get, as product key => role (e.g. {"itsm": "agent"}); each one waits for an approval. |
access_end_date | string (date), can be null | When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors). |
display_name required | string (up to 255) | The name shown everywhere in Kanishu. |
employee_number | string (up to 50), can be null | Your own employee number for them (e.g. from payroll or HR). |
employment_status | string: pre_joining, active, on_leave, leaving, left | pre_joining (joining soon), active, on_leave, leaving (last working day set) or left. |
joining_date | string (date), can be null | Their first working day. |
location_id | string (uuid), can be null | |
manager_person_id | string (uuid), can be null | The manager's People id. |
org_unit_id | string (uuid), can be null | The department or team id, from GET /people-organisation. |
person_type | string: employee, contractor, external, other | employee, contractor, external (auditor, consultant…) or other. |
position_id | string (uuid), can be null | |
preferred_name | string (up to 255), can be null | What they like to be called, if different. |
start_date required | string (date) | Their first working day; their logins are prepared for it. |
work_email | string (email) (up to 255), can be null | Their work email address; how they are matched to logins in the products. |
201 — The new person, as GET /people/{person} returns them.
Reply fields (24) — in data
id | string (uuid) | The person's id in People (a UUID). Use it with /people/{person}. |
display_name | string | The name shown everywhere in Kanishu. |
preferred_name | string, can be null | What they like to be called, if different. |
work_email | string | Their work email address; how they are matched to logins in the products. |
employee_number | string, can be null | Your own employee number for them (e.g. from payroll or HR). |
type | string | employee, contractor, external (auditor, consultant…) or other. |
status | string | pre_joining (joining soon), active, on_leave, leaving (last working day set) or left. |
joining_date | string (date) | Their first working day. |
last_working_date | string (date), can be null | Their last working day, once they are leaving; their logins are switched off after it. |
access_end_date | string (date), can be null | When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors). |
department | object | Their department or team (id and name), from GET /people-organisation. |
department.id | string (uuid) | |
department.name | string | |
position | object | Their job position (id and name). |
position.id | string (uuid) | |
position.name | string | |
location | object | Their office or site (id and name). |
location.id | string (uuid) | |
location.name | string | |
manager | object, can be null | Their manager in People (id and display_name). |
manager.id | string (uuid) | |
manager.display_name | string | |
created_at | string (date and time, ISO 8601) | |
updated_at | string (date and time, ISO 8601) |
GET /api/v1/people/{person}
Get one of people · scope people:read
| Parameter | In | Type | About |
|---|---|---|---|
person required | path | integer | |
fields | query | string | Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back. |
200 — OK. The record is in `data`, with its version in the `ETag` header.
Reply fields (24) — in data
id | string (uuid) | The person's id in People (a UUID). Use it with /people/{person}. |
display_name | string | The name shown everywhere in Kanishu. |
preferred_name | string, can be null | What they like to be called, if different. |
work_email | string | Their work email address; how they are matched to logins in the products. |
employee_number | string, can be null | Your own employee number for them (e.g. from payroll or HR). |
type | string | employee, contractor, external (auditor, consultant…) or other. |
status | string | pre_joining (joining soon), active, on_leave, leaving (last working day set) or left. |
joining_date | string (date) | Their first working day. |
last_working_date | string (date), can be null | Their last working day, once they are leaving; their logins are switched off after it. |
access_end_date | string (date), can be null | When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors). |
department | object | Their department or team (id and name), from GET /people-organisation. |
department.id | string (uuid) | |
department.name | string | |
position | object | Their job position (id and name). |
position.id | string (uuid) | |
position.name | string | |
location | object | Their office or site (id and name). |
location.id | string (uuid) | |
location.name | string | |
manager | object, can be null | Their manager in People (id and display_name). |
manager.id | string (uuid) | |
manager.display_name | string | |
created_at | string (date and time, ISO 8601) | |
updated_at | string (date and time, ISO 8601) |
Need fewer? Add ?fields= with the names you want, e.g. ?fields=display_name,preferred_name.
PATCH /api/v1/people/{person}
Change one of people · scope people:write
| Parameter | In | Type | About |
|---|---|---|---|
person required | path | integer |
Request fields (JSON body) — send only the fields you change
access_end_date | string (date), can be null | When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors). |
display_name | string (up to 255) | The name shown everywhere in Kanishu. |
employee_number | string (up to 50), can be null | Your own employee number for them (e.g. from payroll or HR). |
employment_status | string: pre_joining, active, on_leave, leaving, left | pre_joining (joining soon), active, on_leave, leaving (last working day set) or left. |
joining_date | string (date), can be null | Their first working day. |
location_id | string (uuid), can be null | |
manager_person_id | string (uuid), can be null | The manager's People id. |
org_unit_id | string (uuid), can be null | The department or team id, from GET /people-organisation. |
person_type | string: employee, contractor, external, other | employee, contractor, external (auditor, consultant…) or other. |
position_id | string (uuid), can be null | |
preferred_name | string (up to 255), can be null | What they like to be called, if different. |
work_email | string (email) (up to 255), can be null | Their work email address; how they are matched to logins in the products. |
200 — OK. The record is in `data`, with its version in the `ETag` header.
Reply fields (24) — in data
id | string (uuid) | The person's id in People (a UUID). Use it with /people/{person}. |
display_name | string | The name shown everywhere in Kanishu. |
preferred_name | string, can be null | What they like to be called, if different. |
work_email | string | Their work email address; how they are matched to logins in the products. |
employee_number | string, can be null | Your own employee number for them (e.g. from payroll or HR). |
type | string | employee, contractor, external (auditor, consultant…) or other. |
status | string | pre_joining (joining soon), active, on_leave, leaving (last working day set) or left. |
joining_date | string (date) | Their first working day. |
last_working_date | string (date), can be null | Their last working day, once they are leaving; their logins are switched off after it. |
access_end_date | string (date), can be null | When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors). |
department | object | Their department or team (id and name), from GET /people-organisation. |
department.id | string (uuid) | |
department.name | string | |
position | object | Their job position (id and name). |
position.id | string (uuid) | |
position.name | string | |
location | object | Their office or site (id and name). |
location.id | string (uuid) | |
location.name | string | |
manager | object, can be null | Their manager in People (id and display_name). |
manager.id | string (uuid) | |
manager.display_name | string | |
created_at | string (date and time, ISO 8601) | |
updated_at | string (date and time, ISO 8601) |
POST /api/v1/people/{person}/leave
Record a leaver (logins switched off after the last working day, or now if urgent) · scope people:write
| Parameter | In | Type | About |
|---|---|---|---|
person required | path | integer |
Request fields (JSON body)
last_working_date required | string (date) | Their last working day, once they are leaving; their logins are switched off after it. |
reason | string (up to 500), can be null | Why they are leaving (kept in People's History). |
urgent | boolean | true to switch their logins off now instead of after the last working day. |
200 — The person, as GET /people/{person} returns them.
Reply fields (24) — in data
id | string (uuid) | The person's id in People (a UUID). Use it with /people/{person}. |
display_name | string | The name shown everywhere in Kanishu. |
preferred_name | string, can be null | What they like to be called, if different. |
work_email | string | Their work email address; how they are matched to logins in the products. |
employee_number | string, can be null | Your own employee number for them (e.g. from payroll or HR). |
type | string | employee, contractor, external (auditor, consultant…) or other. |
status | string | pre_joining (joining soon), active, on_leave, leaving (last working day set) or left. |
joining_date | string (date) | Their first working day. |
last_working_date | string (date), can be null | Their last working day, once they are leaving; their logins are switched off after it. |
access_end_date | string (date), can be null | When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors). |
department | object | Their department or team (id and name), from GET /people-organisation. |
department.id | string (uuid) | |
department.name | string | |
position | object | Their job position (id and name). |
position.id | string (uuid) | |
position.name | string | |
location | object | Their office or site (id and name). |
location.id | string (uuid) | |
location.name | string | |
manager | object, can be null | Their manager in People (id and display_name). |
manager.id | string (uuid) | |
manager.display_name | string | |
created_at | string (date and time, ISO 8601) | |
updated_at | string (date and time, ISO 8601) |
POST /api/v1/people/{person}/move
Move a person (department, manager, position or location) from a date · scope people:write
| Parameter | In | Type | About |
|---|---|---|---|
person required | path | integer |
Request fields (JSON body)
department_id | string (uuid), can be null | The department or team they move to, from GET /people-organisation. |
effective_date required | string (date) | The date the move takes effect. |
location_id | string (uuid), can be null | |
manager_id | string (uuid), can be null | Their new manager's People id. |
position_id | string (uuid), can be null |
200 — The person, as GET /people/{person} returns them.
Reply fields (24) — in data
id | string (uuid) | The person's id in People (a UUID). Use it with /people/{person}. |
display_name | string | The name shown everywhere in Kanishu. |
preferred_name | string, can be null | What they like to be called, if different. |
work_email | string | Their work email address; how they are matched to logins in the products. |
employee_number | string, can be null | Your own employee number for them (e.g. from payroll or HR). |
type | string | employee, contractor, external (auditor, consultant…) or other. |
status | string | pre_joining (joining soon), active, on_leave, leaving (last working day set) or left. |
joining_date | string (date) | Their first working day. |
last_working_date | string (date), can be null | Their last working day, once they are leaving; their logins are switched off after it. |
access_end_date | string (date), can be null | When their access to Kanishu products ends, if earlier or later than the last working day (e.g. contractors). |
department | object | Their department or team (id and name), from GET /people-organisation. |
department.id | string (uuid) | |
department.name | string | |
position | object | Their job position (id and name). |
position.id | string (uuid) | |
position.name | string | |
location | object | Their office or site (id and name). |
location.id | string (uuid) | |
location.name | string | |
manager | object, can be null | Their manager in People (id and display_name). |
manager.id | string (uuid) | |
manager.display_name | string | |
created_at | string (date and time, ISO 8601) | |
updated_at | string (date and time, ISO 8601) |
Policies
GET /api/v1/policies
List policies · scope policies:read
| Parameter | In | Type | About |
|---|---|---|---|
fields | query | string | Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back. |
include | query | string | 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`). |
200 — Every matching record in one answer.
Reply fields (12) — each record in data
id | integer | |
title | string | |
category | string | The policy's category (e.g. IT_SECURITY). |
version_label | string | The published version (e.g. 1.0). |
published_at | string (date and time, ISO 8601) | When this version was published. |
content_hash | string | SHA-256 of the published text: if it changes, the policy changed. |
controls | list | 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). |
controls[].framework | string | The framework key (iso27001_2022, soc2_tsc, dpdp_2023, gdpr). |
controls[].control_ref | string | The control's reference in that framework (e.g. A.5.1). |
controls[].title | string | |
controls[].rationale | string, can be null | Why the policy supports the control, if recorded. |
controls[].reviewed_at | string (date and time, ISO 8601), can be null | When an approver signed the mapping off, or null. |
Need fewer? Add ?fields= with the names you want, e.g. ?fields=title,category.
GET /api/v1/policies/{policy}
Get one of policies · scope policies:read
| Parameter | In | Type | About |
|---|---|---|---|
policy required | path | integer | |
fields | query | string | Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back. |
include | query | string | 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`). |
200 — OK. The record is in `data`, with its version in the `ETag` header.
Reply fields (13) — in data
id | integer | |
title | string | |
category | string | The policy's category (e.g. IT_SECURITY). |
version_label | string | The published version (e.g. 1.0). |
published_at | string (date and time, ISO 8601) | When this version was published. |
content_hash | string | SHA-256 of the published text: if it changes, the policy changed. |
sections | object | The policy text by section: purpose, scope, statements, responsibilities and related documents. |
sections.purpose | string | |
sections.scope | string | |
sections.statements | list of string | |
sections.responsibilities | list of string | |
sections.related | string | |
controls | list | 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). |
Need fewer? Add ?fields= with the names you want, e.g. ?fields=title,category.
Read
GET /api/v1/read-events
Who opened and who accepted each policy · scope reads:read
| Parameter | In | Type | About |
|---|---|---|---|
since_id | query | integer | Return events after this id: pass the next_since_id from your last call. Start with 0. |
limit | query | integer | At most this many events (default 200, at most 500). |
fields | query | string | Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back. |
include | query | string | Related records in the same answer, comma-separated: `policy` — The policy the event is about: id, title, category (needs `policies:read`). |
200 — 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.
Reply fields (8) — each record in data
Also in the answer: next_since_id.
id | integer | |
policy_id | integer | |
version_label | string | The policy version the person read. |
employee_ref | string | Your own id for the person, as you sent it when creating the read link. |
employee_name | string, can be null | |
event | string: OPENED, ACCEPTED | OPENED (the person opened the policy) or ACCEPTED (they clicked to accept it). |
integration | string, can be null | Which token or screen sent the link. |
occurred_at | string (date and time, ISO 8601) | When it happened. |
Need fewer? Add ?fields= with the names you want, e.g. ?fields=policy_id,version_label.
POST /api/v1/read-sessions
Send a person a policy to read and accept · scope reads:write
Request fields (JSON body)
policy_id required | integer | A published policy (GET /policies). |
employee_ref required | string (up to 255) | Your own id for the person (employee number, email…). It comes back in the read-events feed. |
employee_name | string (up to 255) | Shown to the person and in the records. Optional. |
201 — 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.
Reply fields (2)
url | string (uri) | The link to open in the person's browser (for that person only). |
expires_at | string (date and time, ISO 8601) | When the link stops working. |