ITAM API reference

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.

GET /api/v1/assets

List assets · scope assets:read

Parameter	In	Type	About
`page`	query	integer	Page number, from 1.
`per_page`	query	integer	Items a page (default 25, at most 100).
`q`	query	string	Search text.
`filter[category]`	query	string	Only records with this value; several values comma-separated mean "any of".
`filter[status]`	query	string	Only records with this value; several values comma-separated mean "any of".
`filter[department]`	query	string	Only records with this value; several values comma-separated mean "any of".
`filter[vendor]`	query	string	Only records with this value; several values comma-separated mean "any of".
`filter[external_vendor_id]`	query	string	Only records with this value; several values comma-separated mean "any of".
`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: `licenses` — The software licences allocated to the asset, as GET /licenses returns them (needs `licenses:read`).

200 — A page of results.

Reply fields (32) — each record in data

Also in the answer: meta, links.

`id`	integer
`asset_tag`	string	Your organisation's tag for the asset (unique).
`name`	string
`category`	string	Asset category (e.g. Laptop, Server).
`sub_category`	string, can be null	Finer category within it.
`status`	string	in_stock, assigned, in_repair, retired or disposed.
`assigned_to`	object, can be null	The person the asset is assigned to (id, name, email), or null.
`assigned_to.id`	string (uuid)
`assigned_to.name`	string
`assigned_to.email`	string
`department`	string
`location`	string
`warranty_end_date`	string (date)
`purchase_cost`	string	Purchase price in the asset's currency.
`currency`	string
`created_at`	string (date and time, ISO 8601)
`updated_at`	string (date and time, ISO 8601)
`processor`	string, can be null
`ram`	string, can be null	Memory, as recorded (e.g. 16 GB).
`storage`	string, can be null	Disk storage, as recorded (e.g. 512 GB SSD).
`operating_system`	string, can be null
`os_version`	string, can be null
`purchase_date`	string (date)
`manufacturer`	string
`model_number`	string
`warranty_status`	string	active or expired, from warranty_end_date; null when no warranty date is recorded.
`amc_status`	string, can be null	active or expired, from the maintenance contract (AMC) end date; null when none.
`service_record_summary`	object	Repairs and services recorded for the asset: count and the most recent service date.
`service_record_summary.count`	integer
`service_record_summary.most_recent_service_date`	string (date), can be null
`license_count`	integer	How many software licences are allocated to the asset (?include=licenses lists them).
`licenses`	list	Only with ?include=licenses. The software licences allocated to the asset, as GET /licenses returns them.

Need fewer? Add ?fields= with the names you want, e.g. ?fields=asset_tag,name.

POST /api/v1/assets

Create in assets · scope assets:write

Request fields (JSON body)

`amc_cost`	number, can be null
`amc_end_date`	string (date), can be null
`amc_provider`	string (up to 255), can be null	Who provides the annual maintenance contract (AMC).
`amc_start_date`	string (date), can be null
`asset_tag` required	string (up to 100)	Your organisation's tag for the asset (unique).
`category_id` required	integer
`currency`	string, can be null
`current_book_value`	number, can be null	Value after depreciation (audit feed).
`custom_fields_json`	string, can be null	Your organisation's own extra fields, by field name.
`department_id`	integer, can be null
`depreciation_method`	string (up to 100), can be null	How the book value is worked out over the asset's life.
`expected_useful_life_years`	integer, can be null	Years over which the asset is depreciated.
`funding_source`	string (up to 255), can be null	Which budget paid for it (e.g. capex, a project).
`fx_rate_override`	number, can be null	An exchange rate to use instead of the day's reference rate (1 unit of currency in home currency).
`hostname`	string (up to 255), can be null
`ip_address`	string (up to 100), can be null
`location_id`	integer, can be null
`mac_address`	string (up to 100), can be null
`manufacturer`	string (up to 255), can be null
`model_number`	string (up to 255), can be null
`name` required	string (up to 255)
`operating_system`	string (up to 100), can be null
`os_version`	string (up to 100), can be null
`payment_terms`	string (up to 255), can be null
`processor`	string (up to 255), can be null
`purchase_cost`	number, can be null	Purchase price in the asset's currency.
`purchase_date`	string (date), can be null
`purchase_order_number`	string (up to 100), can be null
`ram`	string (up to 100), can be null	Memory, as recorded (e.g. 16 GB).
`screen_size`	string (up to 50), can be null
`serial_number`	string (up to 255), can be null
`storage`	string (up to 100), can be null	Disk storage, as recorded (e.g. 512 GB SSD).
`sub_category`	string (up to 100), can be null	Finer category within it.
`vendor_id`	integer, can be null	The supplier, from Vendor management (if you use it); vendor_name otherwise.
`vendor_name`	string (up to 255), can be null
`warranty_end_date`	string (date), can be null
`warranty_start_date`	string (date), can be null

201 — Created. The record is in `data`; its address in `Location`.

Reply fields (31) — in data

`id`	integer
`asset_tag`	string	Your organisation's tag for the asset (unique).
`name`	string
`category`	string	Asset category (e.g. Laptop, Server).
`sub_category`	string, can be null	Finer category within it.
`status`	string	in_stock, assigned, in_repair, retired or disposed.
`assigned_to`	object, can be null	The person the asset is assigned to (id, name, email), or null.
`assigned_to.id`	string (uuid)
`assigned_to.name`	string
`assigned_to.email`	string
`department`	string
`location`	string
`warranty_end_date`	string (date)
`purchase_cost`	string	Purchase price in the asset's currency.
`currency`	string
`created_at`	string (date and time, ISO 8601)
`updated_at`	string (date and time, ISO 8601)
`processor`	string, can be null
`ram`	string, can be null	Memory, as recorded (e.g. 16 GB).
`storage`	string, can be null	Disk storage, as recorded (e.g. 512 GB SSD).
`operating_system`	string, can be null
`os_version`	string, can be null
`purchase_date`	string (date)
`manufacturer`	string
`model_number`	string
`warranty_status`	string	active or expired, from warranty_end_date; null when no warranty date is recorded.
`amc_status`	string, can be null	active or expired, from the maintenance contract (AMC) end date; null when none.
`service_record_summary`	object	Repairs and services recorded for the asset: count and the most recent service date.
`service_record_summary.count`	integer
`service_record_summary.most_recent_service_date`	string (date), can be null
`license_count`	integer	How many software licences are allocated to the asset (?include=licenses lists them).

GET /api/v1/assets/audit-feed

Audit Feed (assets audit feed) · scope assets:audit-read

Parameter	In	Type	About
`page_size`	query	integer	Answer in pages of this many records (10–2000). Without it, everything comes back at once.
`after`	query	integer	The `meta.next_after` from the previous page (start with 0).
`fields`	query	string	Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back.

200 — Records in id order. With page_size, `meta.next_after` is the `after` for the next page (null on the last).

Reply fields (20) — each record in data

Also in the answer: meta.

`id`	integer
`asset_tag`	string	Your organisation's tag for the asset (unique).
`name`	string
`category`	string	Asset category (e.g. Laptop, Server).
`status`	string	in_stock, assigned, in_repair, retired or disposed.
`current_book_value`	string, can be null	Value after depreciation (audit feed).
`expected_useful_life_years`	integer, can be null	Years over which the asset is depreciated.
`purchase_date`	string (date), can be null
`disposal_date`	string (date), can be null
`data_wipe_confirmed`	boolean	true when wiping the data was confirmed before disposal.
`destruction_certificate_reference`	string, can be null	Reference of the certificate of destruction, for disposed assets.
`serial_number`	string, can be null
`hostname`	string, can be null
`purchase_cost`	string, can be null	Purchase price in the asset's currency.
`last_seen_at`	string (date and time, ISO 8601), can be null	When network discovery last saw the device.
`last_audit_scan_at`	string (date and time, ISO 8601), can be null	When the asset was last scanned in a physical audit.
`assignment_date`	string (date), can be null
`assignee_name`	string, can be null
`assignee_email`	string, can be null
`assignee_person_uuid`	string (uuid), can be null	The assigned person's People id.

Need fewer? Add ?fields= with the names you want, e.g. ?fields=asset_tag,name.

GET /api/v1/assets/{asset}

Get one of assets · scope assets:read

Parameter	In	Type	About
`asset` 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: `licenses` — The software licences allocated to the asset, as GET /licenses returns them (needs `licenses:read`).

200 — OK. The record is in `data`, with its version in the `ETag` header.

Reply fields (32) — in data

`id`	integer
`asset_tag`	string	Your organisation's tag for the asset (unique).
`name`	string
`category`	string	Asset category (e.g. Laptop, Server).
`sub_category`	string, can be null	Finer category within it.
`status`	string	in_stock, assigned, in_repair, retired or disposed.
`assigned_to`	object, can be null	The person the asset is assigned to (id, name, email), or null.
`assigned_to.id`	string (uuid)
`assigned_to.name`	string
`assigned_to.email`	string
`department`	string
`location`	string
`warranty_end_date`	string (date)
`purchase_cost`	string	Purchase price in the asset's currency.
`currency`	string
`created_at`	string (date and time, ISO 8601)
`updated_at`	string (date and time, ISO 8601)
`processor`	string, can be null
`ram`	string, can be null	Memory, as recorded (e.g. 16 GB).
`storage`	string, can be null	Disk storage, as recorded (e.g. 512 GB SSD).
`operating_system`	string, can be null
`os_version`	string, can be null
`purchase_date`	string (date)
`manufacturer`	string
`model_number`	string
`warranty_status`	string	active or expired, from warranty_end_date; null when no warranty date is recorded.
`amc_status`	string, can be null	active or expired, from the maintenance contract (AMC) end date; null when none.
`service_record_summary`	object	Repairs and services recorded for the asset: count and the most recent service date.
`service_record_summary.count`	integer
`service_record_summary.most_recent_service_date`	string (date), can be null
`license_count`	integer	How many software licences are allocated to the asset (?include=licenses lists them).
`licenses`	list	Only with ?include=licenses. The software licences allocated to the asset, as GET /licenses returns them.

Need fewer? Add ?fields= with the names you want, e.g. ?fields=asset_tag,name.

PATCH /api/v1/assets/{asset}

Change one of assets · scope assets:write

Parameter	In	Type	About
`asset` required	path	integer

Request fields (JSON body) — send only the fields you change

`amc_cost`	number, can be null
`amc_end_date`	string (date), can be null
`amc_provider`	string (up to 255), can be null	Who provides the annual maintenance contract (AMC).
`amc_start_date`	string (date), can be null
`category_id`	integer
`currency`	string, can be null
`current_book_value`	number, can be null	Value after depreciation (audit feed).
`custom_fields_json`	string, can be null	Your organisation's own extra fields, by field name.
`department_id`	integer, can be null
`deployment_notes`	string (up to 1000), can be null
`depreciation_method`	string (up to 100), can be null	How the book value is worked out over the asset's life.
`enrolled_in_mdm_at`	string (date), can be null	When the device was enrolled in mobile device management.
`expected_useful_life_years`	integer, can be null	Years over which the asset is depreciated.
`funding_source`	string (up to 255), can be null	Which budget paid for it (e.g. capex, a project).
`fx_rate_override`	number, can be null	An exchange rate to use instead of the day's reference rate (1 unit of currency in home currency).
`hostname`	string (up to 255), can be null
`ip_address`	string (up to 100), can be null
`location_id`	integer, can be null
`mac_address`	string (up to 100), can be null
`manufacturer`	string (up to 255), can be null
`model_number`	string (up to 255), can be null
`name`	string (up to 255)
`operating_system`	string (up to 100), can be null
`os_imaged_at`	string (date), can be null	When the operating system image was installed.
`os_version`	string (up to 100), can be null
`payment_terms`	string (up to 255), can be null
`processor`	string (up to 255), can be null
`purchase_cost`	number, can be null	Purchase price in the asset's currency.
`purchase_date`	string (date), can be null
`purchase_order_number`	string (up to 100), can be null
`ram`	string (up to 100), can be null	Memory, as recorded (e.g. 16 GB).
`screen_size`	string (up to 50), can be null
`security_agent_installed_at`	string (date), can be null	When the security agent was installed.
`serial_number`	string (up to 255), can be null
`storage`	string (up to 100), can be null	Disk storage, as recorded (e.g. 512 GB SSD).
`sub_category`	string (up to 100), can be null	Finer category within it.
`vendor_id`	integer, can be null	The supplier, from Vendor management (if you use it); vendor_name otherwise.
`vendor_name`	string (up to 255), can be null
`warranty_end_date`	string (date), can be null
`warranty_start_date`	string (date), can be null

200 — OK. The record is in `data`, with its version in the `ETag` header.

Reply fields (31) — in data

`id`	integer
`asset_tag`	string	Your organisation's tag for the asset (unique).
`name`	string
`category`	string	Asset category (e.g. Laptop, Server).
`sub_category`	string, can be null	Finer category within it.
`status`	string	in_stock, assigned, in_repair, retired or disposed.
`assigned_to`	object, can be null	The person the asset is assigned to (id, name, email), or null.
`assigned_to.id`	string (uuid)
`assigned_to.name`	string
`assigned_to.email`	string
`department`	string
`location`	string
`warranty_end_date`	string (date)
`purchase_cost`	string	Purchase price in the asset's currency.
`currency`	string
`created_at`	string (date and time, ISO 8601)
`updated_at`	string (date and time, ISO 8601)
`processor`	string, can be null
`ram`	string, can be null	Memory, as recorded (e.g. 16 GB).
`storage`	string, can be null	Disk storage, as recorded (e.g. 512 GB SSD).
`operating_system`	string, can be null
`os_version`	string, can be null
`purchase_date`	string (date)
`manufacturer`	string
`model_number`	string
`warranty_status`	string	active or expired, from warranty_end_date; null when no warranty date is recorded.
`amc_status`	string, can be null	active or expired, from the maintenance contract (AMC) end date; null when none.
`service_record_summary`	object	Repairs and services recorded for the asset: count and the most recent service date.
`service_record_summary.count`	integer
`service_record_summary.most_recent_service_date`	string (date), can be null
`license_count`	integer	How many software licences are allocated to the asset (?include=licenses lists them).

DELETE /api/v1/assets/{asset}

Delete one of assets · scope assets:write

Parameter	In	Type	About
`asset` required	path	integer

204 — Deleted.

POST /api/v1/assets/{asset}/reclaim

Reclaim (assets reclaim) · scope assets:write

Parameter	In	Type	About
`asset` required	path	integer

200 — OK. The record is in `data`, with its version in the `ETag` header.

Reply fields (31) — in data

`id`	integer
`asset_tag`	string	Your organisation's tag for the asset (unique).
`name`	string
`category`	string	Asset category (e.g. Laptop, Server).
`sub_category`	string, can be null	Finer category within it.
`status`	string	in_stock, assigned, in_repair, retired or disposed.
`assigned_to`	object, can be null	The person the asset is assigned to (id, name, email), or null.
`assigned_to.id`	string (uuid)
`assigned_to.name`	string
`assigned_to.email`	string
`department`	string
`location`	string
`warranty_end_date`	string (date)
`purchase_cost`	string	Purchase price in the asset's currency.
`currency`	string
`created_at`	string (date and time, ISO 8601)
`updated_at`	string (date and time, ISO 8601)
`processor`	string, can be null
`ram`	string, can be null	Memory, as recorded (e.g. 16 GB).
`storage`	string, can be null	Disk storage, as recorded (e.g. 512 GB SSD).
`operating_system`	string, can be null
`os_version`	string, can be null
`purchase_date`	string (date)
`manufacturer`	string
`model_number`	string
`warranty_status`	string	active or expired, from warranty_end_date; null when no warranty date is recorded.
`amc_status`	string, can be null	active or expired, from the maintenance contract (AMC) end date; null when none.
`service_record_summary`	object	Repairs and services recorded for the asset: count and the most recent service date.
`service_record_summary.count`	integer
`service_record_summary.most_recent_service_date`	string (date), can be null
`license_count`	integer	How many software licences are allocated to the asset (?include=licenses lists them).

GET /api/v1/assets/{asset}/same-model

Same Model (assets same model) · scope assets:read

Parameter	In	Type	About
`asset` 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 (3) — in data

`manufacturer`	string
`model_number`	string
`asset_ids`	list of integer	Ids of assets of the same make and model.

Need fewer? Add ?fields= with the names you want, e.g. ?fields=manufacturer,model_number.

GET /api/v1/configuration-items

List configuration items · scope cis:read

Parameter	In	Type	About
`page`	query	integer	Page number, from 1.
`per_page`	query	integer	Items a page (default 25, at most 100).
`q`	query	string	Search text.
`filter[asset_id]`	query	string	Only records with this value; several values comma-separated mean "any of".
`filter[ids]`	query	string	Only records with this value; several values comma-separated mean "any of".
`filter[ci_class]`	query	string	Only records with this value; several values comma-separated mean "any of".
`filter[environment]`	query	string	Only records with this value; several values comma-separated mean "any of".
`filter[criticality]`	query	string	Only records with this value; several values comma-separated mean "any of".
`sort`	query	string	Comma-separated; prefix - for descending. Allowed: name, created_at, updated_at. Default: name.
`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 (26) — each record in data

Also in the answer: meta, links.

`id`	integer
`name`	string
`class`	string	What kind of item: application, server, database, network, endpoint, cloud_resource, storage_backup, identity_certificate, external_service, software_license or other.
`lifecycle_state`	string	planned, in_build, live, retiring or retired.
`operational_status`	string	operational, degraded, down, maintenance or unknown.
`environment`	string, can be null	production, test, development or disaster_recovery.
`criticality`	string, can be null	Business criticality: critical, high, medium or low.
`asset`	object, can be null	The asset behind the item, if any.
`asset.id`	integer
`asset.asset_tag`	string
`asset.name`	string
`asset.category`	string
`license_id`	integer, can be null	The licence behind the item, if it is a software licence.
`relationships`	list	How the item connects to others (depends on, runs on, …).
`relationships[].type`	string
`relationships[].label`	string	The relationship in words, as read in that direction.
`relationships[].direction`	string	outgoing (this item → target) or incoming (target → this item).
`relationships[].target_ci_id`	integer	The other item's id.
`relationships[].target`	object
`relationships[].target.id`	integer, can be null
`relationships[].target.name`	string
`relationships[].target.asset_tag`	string, can be null
`services`	list	The business services that rely on the item.
`services[].id`	integer
`services[].name`	string
`services[].criticality`	string

Need fewer? Add ?fields= with the names you want, e.g. ?fields=name,class.

GET /api/v1/configuration-items/{configurationItem}

Get one of configuration items · scope cis:read

Parameter	In	Type	About
`configurationItem` 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 (23) — in data

`id`	integer
`name`	string
`class`	string	What kind of item: application, server, database, network, endpoint, cloud_resource, storage_backup, identity_certificate, external_service, software_license or other.
`lifecycle_state`	string	planned, in_build, live, retiring or retired.
`operational_status`	string	operational, degraded, down, maintenance or unknown.
`environment`	string, can be null	production, test, development or disaster_recovery.
`criticality`	string, can be null	Business criticality: critical, high, medium or low.
`asset`	object, can be null	The asset behind the item, if any.
`asset.id`	integer
`asset.asset_tag`	string
`asset.name`	string
`asset.category`	string
`license_id`	integer, can be null	The licence behind the item, if it is a software licence.
`relationships`	list	How the item connects to others (depends on, runs on, …).
`relationships[].type`	string
`relationships[].label`	string	The relationship in words, as read in that direction.
`relationships[].direction`	string	outgoing (this item → target) or incoming (target → this item).
`relationships[].target_ci_id`	integer	The other item's id.
`relationships[].target`	object
`relationships[].target.id`	integer, can be null
`relationships[].target.name`	string
`relationships[].target.asset_tag`	string, can be null
`services`	list	The business services that rely on the item.

Need fewer? Add ?fields= with the names you want, e.g. ?fields=name,class.

GET /api/v1/discovery/config

Config (discovery config) · scope discovery:report

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 (11) — in data

`name`	string	The collector's name.
`subnets`	list of string	Network ranges the collector should scan.
`scan_frequency_hours`	integer	How often to scan.
`credentials`	string	Always stored_on_collector: scan credentials stay on your collector and are never sent to Kanishu.
`settings`	object	Scan limits and timeouts the collector should use (addresses, ports, timeouts, batch size).
`settings.max_addresses`	integer
`settings.tcp_ports`	list
`settings.ping_timeout_ms`	integer
`settings.snmp_timeout_ms`	integer
`settings.cim_timeout_sec`	integer
`settings.batch_size`	integer

Need fewer? Add ?fields= with the names you want, e.g. ?fields=name,subnets.

POST /api/v1/discovery/scans

Submit Scan (discovery scans) · scope discovery:report

Request fields (JSON body)

`devices`	list
`devices[].bios_uuid`	string (up to 64), can be null
`devices[].discovery_methods`	list, can be null	How the device was found (e.g. ping, snmp, wmi).
`devices[].hostname`	string (up to 255), can be null
`devices[].ip_address`	string (up to 45), can be null
`devices[].mac_address`	string (up to 64), can be null
`devices[].probe_status`	list, can be null	How far the probe got for this device.
`devices[].serial_number`	string (up to 255), can be null
`devices[].snmp_data`	list, can be null
`devices[].vendor`	string (up to 255), can be null
`devices[].wmi_data`	list, can be null
`scan`	object, can be null
`scan.batch`	integer
`scan.final`	boolean	true on the last batch of a scan.
`scan.id`	string (up to 64)
`scan.started_at`	string (date), can be null
`scan.summary`	object, can be null
`scan.summary.addresses_alive`	integer, can be null
`scan.summary.addresses_scanned`	integer, can be null
`scan.summary.errors`	list, can be null
`scan.version`	string (up to 20), can be null

200 — OK.

GET /api/v1/licenses

List licenses · scope licenses:read

Parameter	In	Type	About
`page`	query	integer	Page number, from 1.
`per_page`	query	integer	Items a page (default 25, at most 100).
`q`	query	string	Search text.
`filter[vendor]`	query	string	Only records with this value; several values comma-separated mean "any of".
`filter[license_type]`	query	string	Only records with this value; several values comma-separated mean "any of".
`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: `assets` — The assets the licence is allocated to, as GET /assets returns them (needs `assets:read`).

200 — A page of results.

Reply fields (12) — each record in data

Also in the answer: meta, links.

`id`	integer
`name`	string
`vendor`	string	The software publisher or reseller.
`license_type`	string	perpetual, subscription_monthly, subscription_annual, per_seat, per_device, concurrent_user or site.
`seats_purchased`	integer	Seats bought.
`seats_allocated`	integer	Seats allocated to assets.
`seats_available`	integer	Seats still free (purchased minus allocated).
`compliance_status`	string	compliant, over_allocated (more in use than bought) or under_utilized (many seats unused).
`start_date`	string (date)
`expiry_date`	string (date), can be null
`created_at`	string (date and time, ISO 8601)
`assets`	list	Only with ?include=assets. The assets the licence is allocated to, as GET /assets returns them.

Need fewer? Add ?fields= with the names you want, e.g. ?fields=name,vendor.

POST /api/v1/licenses

Create in licenses · scope licenses:write

Request fields (JSON body)

`currency`	string, can be null
`department_id`	integer, can be null
`expiry_date`	string (date), can be null
`fx_rate_override`	number, can be null
`license_key_encrypted`	string (up to 2000), can be null	The licence key; stored encrypted and never shown in full again.
`license_type` required	string: perpetual, subscription_monthly, subscription_annual, per_seat, per_device, concurrent_user, site	perpetual, subscription_monthly, subscription_annual, per_seat, per_device, concurrent_user or site.
`location_id`	integer, can be null
`name` required	string (up to 255)
`seats_purchased` required	integer	Seats bought.
`start_date` required	string (date)
`support_contract_reference`	string (up to 255), can be null	Reference of the support or maintenance contract.
`total_cost`	number, can be null
`unit_cost`	number, can be null
`vendor` required	string (up to 255)	The software publisher or reseller.
`version`	string (up to 255), can be null

201 — Created. The record is in `data`; its address in `Location`.

Reply fields (11) — in data

`id`	integer
`name`	string
`vendor`	string	The software publisher or reseller.
`license_type`	string	perpetual, subscription_monthly, subscription_annual, per_seat, per_device, concurrent_user or site.
`seats_purchased`	integer	Seats bought.
`seats_allocated`	integer	Seats allocated to assets.
`seats_available`	integer	Seats still free (purchased minus allocated).
`compliance_status`	string	compliant, over_allocated (more in use than bought) or under_utilized (many seats unused).
`start_date`	string (date)
`expiry_date`	string (date)
`created_at`	string (date and time, ISO 8601)

GET /api/v1/licenses-compliance-report

Compliance Report (licenses compliance report) · scope reports: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 (2)

`over_allocated`	list	Licences with more seats in use than bought.
`expiring_soon`	list	Licences whose expiry date is near.

Need fewer? Add ?fields= with the names you want, e.g. ?fields=over_allocated,expiring_soon.

GET /api/v1/licenses/{license}

Get one of licenses · scope licenses:read

Parameter	In	Type	About
`license` 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: `assets` — The assets the licence is allocated to, as GET /assets returns them (needs `assets:read`).

200 — OK. The record is in `data`, with its version in the `ETag` header.

Reply fields (12) — in data

`id`	integer
`name`	string
`vendor`	string	The software publisher or reseller.
`license_type`	string	perpetual, subscription_monthly, subscription_annual, per_seat, per_device, concurrent_user or site.
`seats_purchased`	integer	Seats bought.
`seats_allocated`	integer	Seats allocated to assets.
`seats_available`	integer	Seats still free (purchased minus allocated).
`compliance_status`	string	compliant, over_allocated (more in use than bought) or under_utilized (many seats unused).
`start_date`	string (date)
`expiry_date`	string (date)
`created_at`	string (date and time, ISO 8601)
`assets`	list	Only with ?include=assets. The assets the licence is allocated to, as GET /assets returns them.

Need fewer? Add ?fields= with the names you want, e.g. ?fields=name,vendor.

POST /api/v1/licenses/{license}/allocations

Allocate Seat (licenses allocations) · scope licenses:write

Parameter	In	Type	About
`license` required	path	integer

Request fields (JSON body)

`allow_over_allocation`	boolean	true to allocate even when no seats are free (the licence then shows as over_allocated).
`asset_id` required	integer	The asset to allocate the seat to, or take it back from.

200 — OK. The record is in `data`, with its version in the `ETag` header.

Reply fields (11) — in data

`id`	integer
`name`	string
`vendor`	string	The software publisher or reseller.
`license_type`	string	perpetual, subscription_monthly, subscription_annual, per_seat, per_device, concurrent_user or site.
`seats_purchased`	integer	Seats bought.
`seats_allocated`	integer	Seats allocated to assets.
`seats_available`	integer	Seats still free (purchased minus allocated).
`compliance_status`	string	compliant, over_allocated (more in use than bought) or under_utilized (many seats unused).
`start_date`	string (date)
`expiry_date`	string (date)
`created_at`	string (date and time, ISO 8601)

POST /api/v1/licenses/{license}/reclaim-seat

Reclaim Seat (licenses reclaim seat) · scope licenses:write

Parameter	In	Type	About
`license` required	path	integer

Request fields (JSON body)

asset_id required integer The asset to allocate the seat to, or take it back from.

200 — OK. The record is in `data`, with its version in the `ETag` header.

Reply fields (11) — in data

`id`	integer
`name`	string
`vendor`	string	The software publisher or reseller.
`license_type`	string	perpetual, subscription_monthly, subscription_annual, per_seat, per_device, concurrent_user or site.
`seats_purchased`	integer	Seats bought.
`seats_allocated`	integer	Seats allocated to assets.
`seats_available`	integer	Seats still free (purchased minus allocated).
`compliance_status`	string	compliant, over_allocated (more in use than bought) or under_utilized (many seats unused).
`start_date`	string (date)
`expiry_date`	string (date)
`created_at`	string (date and time, ISO 8601)

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.

GET /api/v1/people/assets

List people assets · scope assets:read

Parameter	In	Type	About
`email` required	query	string
`fields`	query	string	Only these fields of each record, comma-separated (e.g. `id,name`; nested: `owner.name`). `id` always comes back.

200 — Every matching record in one answer.

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)

POST /api/v1/people/reclaim

Reclaim (people reclaim) · scope assets:reclaim

Request fields (JSON body)

`email` required	string (email) (up to 255)
`release_licenses`	boolean

200 — OK.

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)

POST /api/v1/vendors/directory-changed

Changed (vendors directory changed) · scope vendors:notify

200 — OK.

ITAM

API access

Assets

Configuration

Discovery

Licenses

People

Vendors