User Documentation
User Documentation
Breadcrumbs

Entities & Endpoints

Overview

Access Integration Service (AIS) provides a set of endpoints to interact with various entities within the system. Below is an overview of the main entities and their purpose.

entities.drawio.svg

Entities & Endpoints

Tenant

Description

Provides basic isolation of customers. Each customer must have at least one assigned tenant. Groups together one or more PACS.

To be able to interact with the PACS agents, you must have a registered tenant.

Actions

  • Register Tenant: Registers a new tenant.

  • Get Tenant: Retrieves detailed information about a specific tenant.

  • Update Tenant: Updates details of a specific tenant.

  • Get Tenant Statistics: Overview of tenant API usage.

Example: Register tenant

  • {URL} is the production environment of HIS: https://his.hidglobal.com/ais/v1

  • {TENANT_ID} is user chosen tenant identification, which must be globally unique.

  • tenantAdministratorUid is the identifier of the user in the HID Authentication Service (matches sub value received in authentication token) to be assigned the TenantAdministrator role.

  • name should be a more user-friendly identifier for this tenant.

  • extensionFields are explained more in-depth here. To use them, they need to first be defined at the tenant level. Essentially, we're stating, "For this tenant, we want to use the following extension fields: the ExtensionField1 which is of type string and will be required during the creation of an identity, and the ExtensionField2 which is of type integer."

This definition applies equally to both identityExtensionFields and visitExtensionFields.

curl --request PUT --url '{URL}/tenant/{TENANT_ID}' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "tenantAdministratorUid": "tenant-administrator-uid",
  "name": "name",
  "identityExtensionFields": {
    "ExtensionField1": {
      "description": "string-extension-field-1",
      "type": "string",
      "required": true
    },
    "ExtensionField2": {
      "description": "integer-extension-field-2",
      "type": "integer"
    }
  }
}
'

Advanced Tenant Configuration

Tenant parameters can be configured either during tenant creation or by updating an existing tenant.

Important: Incorrect configuration of these parameters may cause tenant malfunction. Modify these settings only if you understand their implications, and do so at your own risk.

  • traceLogLevel: Sets the minimum severity level of PACS messages logged at the tenant level. Messages below this level are ignored. Valid values, in order of decreasing severity, are: Critical, Error, Warning, Information, Debug, Trace. The default value is Warning.

  • staleMessageTtl: Specifies the number of seconds an unprocessed message for the PACS system remains on the HIS platform before being deleted. If a message is deleted due to expiration, an error is emitted. The default is 600 seconds. This cannot be set higher than 24 hours due to PII persistence limitations.

  • processedMessagesTtl: Defines the number of seconds a PACS response remains available on the HIS platform before it is deleted. The default is 600 seconds. This cannot be set higher than 24 hours due to PII persistence limitations.

  • polledResponseTtl: Determines the number of seconds a PACS response remains available after it has been picked up by a consumer (to allow for additional retrieval). The default is 60 seconds.

  • reportPacsInactivityAfter: Specifies the number of seconds without network contact after which a PACS system is considered inactive. Inactive PACS systems can still receive queued messages from the HIS platform. The default is 180 seconds.

  • inactivePacsBarredAfter: Sets number of seconds after which, if there is still no network contact following inactivity, the PACS system is considered unavailable and the platform will begin refusing new messages to this PACS. The default is 180 seconds.

Role

Description

The set of permissions defining what actions a user can perform. A user of the integration service API can refer to a person, client application, or PACS agent instance.

Actions

  • List permissions: Lists all permissions available.

  • Create role: Creates a new role for a specific tenant.

  • List roles: Retrieves a list of all roles available for a tenant.

  • Get role: Retrieves details of a specific role within a tenant, including its permissions.

  • Update role: Updates details of a specific role.

  • Remove role: Removes a role from the system and disassociates it from any assignments.

  • Create role assignment: Assigns a role to a specific user, granting them the associated permissions.

  • List role assignments: Lists all assignments for a specific role.

  • Get role assignment: Retrieves details of a specific role assignment.

  • Remove role assignment: Removes a role assignment from a user.

  • List user roles: List role (assignment) for particular user.

Example: Create a role

First, list all available permissions, since some of them will be assigned to the role during its creation:

curl --request GET --url '{URL}/tenant/{TENANT_ID}/permission' \
--header 'Authorization: ••••••'

  • {URL} is the production environment of HIS: https://his.hidglobal.com/ais/v1

  • {TENANT_ID} is user chosen tenant identification, which must be globally unique.

The response from this call should look like this:

{
    "permissions": [
        "RoleCreate",
        "RoleGet",
        "IdentityCreate",
        "IdentityGet",
        ...
    ]
}

Next, create a role with, for example, the IdentityCreate and IdentityGet permissions:

curl --request POST --url '{URL}/tenant/{TENANT_ID}/role' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "name": "role-name",
  "permissions": [
    "IdentityCreate",
    "IdentityGet"
  ]
}'

The response should look like this:

{
  "id": "id-of-new-role",
  ...
}

Finally, the role can be assigned to a specific user:

curl --request POST --url '{URL}/tenant/{TENANT_ID}/role/{ID_OF_NEW_ROLE}/assignment' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "userId": "user-id",
  "pacsId": "pacs-id"

}'

where userId is the identifier of the user to whom we are assigning the role, and pacsId specifies the Agent (PACS) under which the role will be available.

A role assignment is always scoped to a tenant, and optionally to a specific PACS. If you want the role assignment to be done across all PACS systems within the tenant, you can use the * wildcard instead of a specific pacsId.

PACS

Description

  • Represents physical PACS or agent instances. Each PACS has a unique ID for addressing via API.

  • As a user, you register your PACS systems into your tenant.

Actions

  • Register PACS: Adds a new PACS for a tenant.

  • List PACS: Lists all PACS of a tenant.

  • Get PACS details: Retrieves details about a specific PACS.

  • Update PACS: Updates details of a specific PACS.

  • Unregister PACS: Removes PACS from a tenant.

  • Get PACS details response: Retrieves the result of a request to fetch detailed information about a specific PACS.

Example: Register a PACS

You need to register the PACS to be able to configure HIS Agents.

First, you need to get a token from HID Authentication Service for a user with tenant admin rights. You will need an API Technical Account, in which context you ask for a token (typically developed app) and credentials for the Tenant Administrator Account.

How to call the HID Authentication Service API here.

Sample:

curl -v --request POST --url '{AuthNprovider}' 
--user "{clientID}:{secret}" 
--header 'Content-Type: application/x-www-form-urlencoded' 
--data "grant_type=password&username={TenantAdminUsername}&password={password}&scope=openid"

  • {AuthNprovider} is the URL for HID Authentication Service.

  • {clientID} is the client ID of the API Technical Account.

  • {secret} is the secret of the API Technical Account.

  • {TenantAdminUsername} is the username for the Tenant Administrator Account.

  • {password} Password for Tenant Administrator Account.

Now you can call HIS API:

curl --request POST --url '{URL}/tenant/{TENANT_ID}/pacs' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {Token}' \
--data '{
  "pacsId": "pacs-id",
  "agentInstanceUid": "agent-instance-uid",
  "name": "name",
  "identityExtensionFields": {
    "ExtensionField1": {
      "path": "$.self.FirstName"
    },
    "ExtensionField2": {
      "path": "$.ext.ExtensionField2"
    }
  }
}

  • {URL} is the production environment of HIS: https://his.hidglobal.com/ais/v1

  • {TENANT_ID} is user-chosen tenant identification, which must be globally unique.

  • {Token} Token you've got from HID Authorization Service

  • {pacsId} is an identifier defined by the user, unique in the scope of the tenant. It will be used in the requests related to this specific agent.

  • {agentInstanceUid} is the identifier of the agent registration in the HID Authentication Service (represented by the client_id).

  • {name} should be a more user-friendly identifier for this agent. It can include details like the building number or any other descriptive information.

  • The {extensionFields} that were defined during the tenant registration need to be mapped to specific fields. These mappings define the source of the values for each extension field.

    • For {ExtensionField1}, use the path $.self.FirstName, which means the value of this extension field will come from the native field {FirstName} already defined in the PACS.

    • For {ExtensionField2}, use the path $.ext.ExtensionField2, which means the value will come from the newly defined field {ExtensionField2} in the PACS.

    This definition applies equally to both identityExtensionFields and visitExtensionFields.

Identity

Description

  • Represents a person (a.k.a. cardholder) to whom credentials can be assigned to grant access to access units (e.g., employee, visitor, hotel guest).

  • As a user, you manage the identities in each of your registered PACS.

Actions

  • Create identity: Creates a new identity (e.g., employee) within a PACS.

  • List of identities: Lists all identities (e.g., employees) registered in a PACS.

  • Get identity details: Retrieves detailed information about a specific identity.

  • Update identity: Updates details of a specific identity.

  • Remove identity: Removes an identity from the PACS.

  • Activate identity: Performs the identity activation within a PACS.

  • Deactivate identity: Performs the identity deactivation within a PACS.

  • Import identities: Imports multiple identities in a single batch request using an upsert model (create or update). Supports attributes, credentials, accesses and PIN management, with optional removal of unlisted items.

    Export identity: Exports detailed data of a specific identity, including attributes, credentials, accesses and PIN, using the same structure as the import model.

    Export identities: Exports detailed data of multiple identities. Supports pagination and optional filtering by modification date.

  • Get identity response: Retrieves the result of a request involving an identity, such as its retrieval, creation or update.

  • List identities response: Retrieves the result of the request to list identities in a PACS.

Example: Create an identity

  • {URL} is the production environment of HIS: https://his.hidglobal.com/ais/v1

  • {TENANT_ID} is user-chosen tenant identification, which must be globally unique.

  • {PACS_ID} is the unique id of the specific PACS in which you are creating the identity.

  • {externalId} is used to define a custom identifier of the identity.

  • {picture} is a JPG or PNG image encoded in base64, inside the following structure: data:image/jpeg;base64,{BASE64_IMG}.

  • In the {extensionFields}, note that we are only using {ExtensionField2}. As mentioned earlier, {ExtensionField1} maps to the existing native field {FirstName} in the PACS, so it's not storing any value, unlike in the {ExtensionField2}.

curl --request POST --url '{URL}/tenant/{TENANT_ID}/pacs/{PACS_ID}/identity' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "externalId": "external-id",
  "firstName": "first-name",
  "lastName": "last-name",
  "email": "identity@email.com",
  "phone": "+123258654753",
  "picture": "image-encoded-as-base64",
  "extensionFields": {
    "ExtensionField2": 123
  }
}
'

This call is delegated to the agent (PACS), which is why it returns an HTTP 202 Accepted response. The Location header in the response contains a URL that can be long-polled to retrieve the result. The result should look like this; we will need the id of the newly created identity for other calls:

{
  "id": "id-of-new-identity",
  ...
}

Example: Create identities using data import

See Data Import for details.

Credential

Description

  • Unique identification of an identity used to gain physical access.

  • Multiple types of credentials can be assigned to each identity.

  • As a user, you manage your credentials in each of your registered PACS.

Actions

  • Get credential formats: Retrieves all supported credential formats from PACS.

  • Get credential formats response: Retrieves the result of a request related to a listing of credential formats.

  • (Get) Credential response: Retrieves the result of a request involving a credential, such as its retrieval, creation or update.

  • List credential response: Retrieves the result of a request related to a listing of credentials.

Example: See all the credential formats that are supported

  • {URL} is the production environment of HIS: https://his.hidglobal.com/ais/v1

  • {TENANT_ID} is user-chosen tenant identification, which must be globally unique.

  • {PACS_ID} is the unique id of the specific PACS you want to check the credential formats that are supported.

curl --request GET --url '{URL}/tenant/{TENANT_ID}/pacs/{PACS_ID}/credential/formats' \
--header 'Accept: application/json' \
--header 'Authorization: ••••••'

This call is delegated to the agent (PACS), which is why it returns an HTTP 202 Accepted response. The Location header in the response contains a URL that can be long-polled to retrieve the result:

{
  "formats": [
    "HID H10306 34 Bits",
    "HID H10302 37 Bits",
    "HID H10304 37 Bits",
    ...
  ]
}

PIN Credential

Description

  • A PIN is treated as an authentication credential that is bound to a Visit or an Identity. It is not considered a form of two-factor authentication.

  • Each Visit or Identity can be associated with only one PIN.

Actions

  • Add PIN credential to a specified Identity.

  • Read PIN credential from a specified Identity.

  • Update PIN credential of a specified Identity.

  • Delete PIN credential from a specified Identity.

  • Activate PIN credential for a specified Identity.

  • Deactivate PIN credential for a specified Identity.

  • Add PIN credential to a specified Visit.

  • Read PIN credential from a specified Visit.

  • Update PIN credential of a specified Visit.

  • Delete PIN credential from a specified Visit.

  • Activate PIN credential for a specified Visit.

  • Deactivate PIN credential for a specified Visit.

Example: Create a PIN credential for a given identity

  • {URL} is the production environment of HIS: https://his.hidglobal.com/ais/v1

  • {TENANT_ID} is user-chosen tenant identification, which must be globally unique.

  • {PACS_ID} is the unique id of the specific PACS you want to check the credential formats that are supported.

  • {IDENTITY_ID} is the unique id of the identity for which the PIN is created.

curl '{URL}/tenant/{TENANT_ID}/pacs/{PACS_ID}/identity/{IDENTITY_ID}/pin' \
  -H 'authorization: Bearer ...' \
  -H 'content-type: application/json' \
  --data-raw '{"value":"1234"}'

PIN credential support depends on the PACS; check the Agents section to confirm compatibility before use.

Access unit

Description

  • Represents physical access to a location. The granularity depends on the specific PACS configuration (e.g., area, zone, access rule, or cardholder group).

  • Based on particular PACS configurations, an access unit might also contain an access schedule; however, AIS cannot change configured schedules or assign new ones to access units.

  • In case particular PACS provide multiple abstraction layers to group physical accesses (door, door group, cardholder group, etc.), the related agent is configured to provide only one of these layers as an access unit.

  • As a user, you register the access units of each PACS.

Actions

  • List access units: Lists all access units (e.g., doors, zones) in a PACS.

  • Get access unit: Returns access unit details.

  • List access unit identities: Lists all identities associated with a specific access unit in a PACS.

  • List access unit visits: Lists all visits associated with a specific access unit in a PACS.

  • Get access unit response: Retrieves the result of a request related to an access unit, such as assigning or revoking access.

  • List access units response: Retrieves the result of the request for listing access units in a PACS.

Visit

Description

Represents a temporary presence of a person within a PACS, typically for a predefined duration such as a scheduled visit or event.

Actions

  • List visits: Lists all visits registered in a PACS.

  • Get visit: Retrieves detailed information about a specific visit.

  • Create visit: Creates a new visit within a PACS.

  • Update visit: Updates details of a specific visit.

  • Remove visit: Removes a visit from the PACS.

  • Check-in visit: Performs the check-in operation for a visit within a PACS.

  • Check-out visit: Performs the check-out operation for a visit within a PACS.

  • Get visit response: Retrieves the result of a request involving a visit, such as its retrieval, creation or update.

  • Get visits response: Retrieves the result of the request to list visits in a PACS.

Example: Create a visit

Assuming the user with the token has the necessary privileges on the HIS, you can then call the following example endpoint for creating a visit.

Request:

curl --request POST --url '{URL}/tenant/{TENANT_ID}/pacs/{PACS_ID}/visit' \
--header 'Content-Type: application/json' \
--header 'Authorization: {YOUR_TOKEN}' \
--data '{
  "firstName": "John",
  "lastName": "Snow",
  "email": "john@email.com",
  "phoneNumber": "+12345678",
  "picture": "",
  "externalId": "666",
  "extensionFields": {}
}'

  • {URL} is the production environment of HIS: https://his.hidglobal.com/ais/v1

  • {TENANT_ID} is user-chosen tenant identification, which must be globally unique.

  • {PACS_ID} is the unique id of the specific PACS in which you are creating a visit.

Response:

200 OK

Please refer to the API Swagger section for more information.

Example: Create visits using data import

See Data Import for details.

PACS agent

Description

Representation of PACS agent connected to the platform. Functionalities are not intended to be used by the end-users but solely by connected agents.

Actions

  • Get Agent Configuration: Retrieves agent configuration.

  • Get message: Retrieves a message intended for processing by a PACS.

  • Create response: Creates a response for a message that has been processed by a PACS.

  • Write logs: Writes a preformatted JSON log message to stdout, where it can be scraped for further processing.

Health

Description

Useful for monitoring and uptime verification.

Actions

  • Get health: Provides a simple health status of the application, indicating whether the service is operational or not.

Example: 

curl '{URL}/tenant/root/pacs/health'
Healthy

Connections between entities

Identity access

Description

As a user, you can manage the different access units that each identity has assigned.

Actions

  • Assign identity to access unit: Associates an access unit with an identity, granting that identity access to the specified area or resource represented by the access unit.

  • List of identity access units: Lists all access units assigned to a specific identity in a PACS.

  • Remove identity from access unit: Revokes access to a specific access unit from an identity.

Example: Assign an access unit

  • {URL} is the production environment of HIS: https://his.hidglobal.com/ais/v1

  • {TENANT_ID} is user-chosen tenant identification, which must be globally unique.

  • {PACS_ID} is the unique id of the specific PACS in which you are assigning the access unit.

  • {IDENTITY_ID} is the unique id to which you are assigning the access unit.

curl --request POST --url '{URL}/tenant/{TENANT_ID}/pacs/{PACS_ID}/identity/{IDENTITY_ID}/accessUnits' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
  "accessUnitId": "access-unit-id"
}'

Note that in this example, we assign a previously created identity to an access unit.

Identity credential

Description

As a user, you can manage the different credentials that each identity has assigned.

Actions

  • Create credential: Adds a new card for an identity.

  • List identity credentials: Lists all credentials (e.g., cards, tokens) associated with a specific identity in a PACS.

  • Get credential: Retrieves detailed information about a specific credential.

  • Remove credential: Removes a specific credential assigned to an identity.

  • Activate identity credential: Performs the identity credential activation within a PACS.

  • Deactivate identity credential: Performs the identity credential deactivation within a PACS.

Example: Create a new credential

  • {URL} is the production environment of HIS: https://his.hidglobal.com/ais/v1

  • {TENANT_ID} is user-chosen tenant identification, which must be globally unique.

  • {PACS_ID} is the unique id of the specific PACS in which you are assigning the access unit.

  • {IDENTITY_ID} is the unique id to which you are assigning the access unit.

  • {facilityId} is a code representing the facility or site.

  • {cardId} is the identifier of the card.

curl --request POST --url '{URL}/tenant/{TENANT_ID}/pacs/{PACS_ID}/identity/{IDENTITY_ID}/credential' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
    "format": "HID H10302 37 Bits",
    "facilityId": "facility-id",
    "cardId": "card-id"
}'

Note that in this example, we created a new credential with the format HID H10302 37 Bits (that we previously verified).

Visit access

Description

As a user, you can manage the different access units that each visit has assigned.

Actions

  • Assign visit to access unit: Associates an access unit with a visit, granting that visit access to the specified area or resource represented by the access unit.

  • List of visit access units: Lists all access units assigned to a specific visit in a PACS.

  • Remove visit to access unit: Revokes access to a specific access unit from a visit.

Visits are essentially the same as identities: both represent a person with a credential and assigned access unit. The key difference is that a visit has a temporary lifespan, defined by check-in and check-out actions.

Visit credential

Description

As a user, you can manage the different credentials that each visit has assigned.

Actions

  • Create credential: Adds a new card for a visit.

  • List visit credentials: Lists all credentials (e.g., cards, tokens) associated with a specific visit in a PACS.

  • Get credential: Retrieves detailed information about a specific credential.

  • Update credential: Updates details of a specific credential.

  • Remove credential: Removes a specific credential assigned to a visit.

  • Activate visit credential: Performs the visit credential activation within a PACS.

  • Deactivate visit credential: Performs the visit credential deactivation within a PACS.

Visits are essentially the same as identities: both represent a person with a credential and assigned access unit. The key difference is that a visit has a temporary lifespan, defined by check-in and check-out actions.