API basics

The normal ICAP v1 path is:

https://<your-icap-host>/icap/v1/tenant/<tenantId>

Request format

Use application/json for create and PATCH requests.

Content-Type: application/json
Authorization: Bearer <access-token>

PATCH requests use an array of JSON Patch-style operations, not a partial JSON object. The supplied current contract declares this request body as application/json. PATCH requests also need the current If-Match version; see updates and concurrency.

IDs, dates, and response fields

• ICAP creates the resource id. Keep it as an opaque string.

• externalIds are business correlation values that your application supplies. They are distinct from the ICAP id and are useful for reconciliation with HR, visitor-management, or other upstream systems.

• Timestamps use ISO 8601 date-time values. Use UTC where practical.

• Resource representations include service-managed fields such as id, tenantId, version, and, where applicable, audit timestamps. Do not supply or patch service-managed fields. Response bodies vary by operation: use the endpoint's response schema, and do not expect a resource body after 204 No Content.

• Identity and visitor reads omit photos unless includePhoto=true is requested. Individual personal-share reads have a different default; see Filtering and pagination before reading shared personal data.

List responses

List endpoints return a paged envelope:

{
  "items": [],
  "limit": 10,
  "offset": 0,
  "total": 0
}

Use limit and offset deliberately; do not assume that a single response contains every record. Filtering differs by resource—refer to filtering and pagination.

Safe operations

Removal behavior depends on the resource. People, visits, credentials, and access units use soft deletion. Card types, extension field definitions, custom roles, role assignments, and local PACS configuration records are physically removed, subject to their dependency rules. Identity and visitor purge clears specified personal fields while retaining documented metadata and related records. See Privacy and lifecycle before implementing removal or retention workflows.

Use API reference map to find an operation and API Swagger (ICAP)for its current schema and required permission.