Identities

An identity is the durable record for a person who may need ongoing physical access: an employee, contractor, or regular cardholder. It is not an API user, a credential, a PACS record, or an access right.

Create and manage identities through /identity. An identity holds person data, client-provided externalIds, optional custom fields, an active or inactive status, and links to separately managed credentials and access units.

What an identity controls

Use an identity to preserve the person record while cards, permissions, and PACS registrations change. Grant intended access by assigning a credential and access unit to the identity; the identity itself does not grant access.

Lifecycle

An identity is created as active. You can change it between active and inactive while retaining the record. Removal soft-deletes the record; purge clears its specified personal fields and removes it from normal reads.

Create → Active ↔ Inactive
Active or inactive → Remove (soft delete)
Active or inactive → Purge
Soft-deleted → Purge, using a verified current-version procedure

Removal is not a prerequisite for purge. Normal GET and list operations exclude removed records, so plan how to supply the correct version before using a retention workflow that removes a person and purges later. See Privacy and lifecycle. There is no restore endpoint.

Create and find records

externalIds, firstName, and lastName are required on create. An external-ID key/value pair must be unique among non-deleted identities in the tenant. Supply one or more stable source identifiers rather than using the ICAP id as a cross-system key.

Use the identity list endpoint with externalIds, updatedSince, offset, and limit query params for lookup and incremental processing. The externalIds filter matches supplied values, not a particular provider key; use the returned record to confirm the match.

Person photos are excluded unless includePhoto=true. For field-level schemas, use the Identity section of the API reference.

Assignments

Assigning a card or PIN to an identity uses /identity/{identityId}/credential; assigning access uses /identity/{identityId}/accessUnit. List and remove assignments from the same subpaths.

Create credentials and access units first, then use their ICAP IDs in the assignment request. Review credentials and card types and access units for eligibility and mapping considerations.

Replace or revoke a card

Use credential status to revoke a lost, stolen, or retired card. First read the credential to obtain its current version, then PATCH its status to inactive. This changes ICAP's intended credential state; for a PACS-backed tenant, monitor the related transaction before reporting that the physical card is disabled.

OLD_CREDENTIAL_JSON="$(curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/cardCredential/$OLD_CREDENTIAL_ID")"
OLD_CREDENTIAL_VERSION="$(jq --exit-status --raw-output '.version' <<<"$OLD_CREDENTIAL_JSON")"

curl --fail-with-body --silent --show-error \
  --request PATCH "$BASE_URL/cardCredential/$OLD_CREDENTIAL_ID" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --header "If-Match: $OLD_CREDENTIAL_VERSION" \
  --data '[
    { "op": "replace", "path": "/status", "value": "inactive" }
  ]'

A successful response returns the credential with status: "inactive" and an incremented version. This operation requires CardCredentialGet and CardCredentialUpdate.

To replace a card, create the new credential first with POST /cardCredential and its compatible cardType. A credential can have only one active assignment, so at the planned cutover remove the old assignment, then assign the new credential:

curl --fail-with-body --silent --show-error \
  --request DELETE \
  --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/identity/$IDENTITY_ID/credential/$OLD_CREDENTIAL_ID"

curl --fail-with-body --silent --show-error \
  --request POST "$BASE_URL/identity/$IDENTITY_ID/credential" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{
    \"credentialId\": \"$NEW_CREDENTIAL_ID\",
    \"credentialType\": \"cardCredential\"
  }"

Confirm the new assignment with GET /identity/{identityId}/credential, then remove the old credential with its current If-Match version only when retention policy permits it. The cutover needs IdentityCredentialRemove and IdentityCredentialAssign in addition to the credential permissions above. Schedule the change so any gap between removing the old assignment and downstream PACS completion is acceptable.

Employee offboarding

Offboarding begins by making the identity inactive, not by immediately deleting or purging it. Read the identity's current version, then update its business status:

IDENTITY_JSON="$(curl --fail-with-body --silent --show-error \
  --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/identity/$IDENTITY_ID")"
IDENTITY_VERSION="$(jq --exit-status --raw-output '.version' <<<"$IDENTITY_JSON")"

curl --fail-with-body --silent --show-error \
  --request PATCH "$BASE_URL/identity/$IDENTITY_ID" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --header "If-Match: $IDENTITY_VERSION" \
  --data '[
    { "op": "replace", "path": "/status", "value": "inactive" }
  ]'

This requires IdentityGet and IdentityUpdate. Then list the identity's credential and access-unit assignments, revoke or remove access according to the organization’s offboarding policy, and monitor PACS transactions where configured. Soft-delete or purge only after the retention, legal, and downstream-system obligations have been reviewed.

Update safely

Identity PATCH, remove, and purge operations require the identity's current numeric version in If-Match. Do not edit a stale copy; follow updates and concurrency.