Version: 1.0

People

Introduction

People represent credential holders in the access control system.

The person object

{
  "id": 1,
  "firstName": "John",
  "lastName": "Wiegand",
  "email": "john@example.com",
  "photoUrl": "https://panel-1234ABC.pdk.io:443/images/250f7660-267a-11ee-bcc3-a3fcec96bc14",
  "partition": 0,
  "enabled": true,
  "activeDate": "2023-07-17T09:00:00",
  "expireDate": "2023-07-21T17:00:00",
  "customAttributes": {
    "employee_id": 1234567
  },
  "metadata": {},
  "groups": [
    {
      "id": 1,
      "name": "Test Group",
      "partition": 0,
      "metadata": {}
    }
  ],
  "credentials": [
    {
      "id": 1,
      "personId": 1,
      "credentialNumber": 1234567,
      "facilityCode": null,
      "description": null,
      "types": ["card"]
    },
    {
      "id": 2,
      "personId": 1,
      "credentialNumber": null,
      "facilityCode": null,
      "description": "Pending",
      "types": ["touch", "token"]
    }
  ]
}

Property	Type	Description
`id`	Integer	The person ID.
`firstName`	String	The person's first name.
`lastName`	String	The person's last name.
`email`	String	The person's email address.
`photoUrl`	String	The URL of the person's photo.
`partition`	Integer	The ID of the partition that this person is associated with.
`enabled`	Boolean	Whether rules will be processed for this person.
`activeDate`	String	The date rules will start processing for this person. This is formatted as `YYYY-MM-DDTHH:mm:ss`.
`expireDate`	String	The date rules will stop processing for this person. This is formatted as `YYYY-MM-DDTHH:mm:ss`.
`pin`	String	The person's PIN code.
`duressPin`	String	The person's duress PIN code.
`customAttributes`	Object	An object containing custom field values for this person.
`metadata`	Object	A user-defined metadata object.
`groups`	Object[]	An array of group objects representing the groups this person is assigned to.
`credentials`	Object[]	An array of credential objects representing the credentials issued to this person.

Basic Endpoints

Create a person

Request

POST https://panel-{{panel_id}}.pdk.io/api/persons HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Wiegand"
}

Parameter	Location	Type	Required	Description
`panel_id`	Path	String	Yes	The cloud node serial number.
`panel_token`	Header	String	Yes	A valid panel token.
`firstName`	Body	String	Yes	The person's first name. The maximum length is 35 characters.
`lastName`	Body	String	Yes	The person's last name. The maximum length is 35 characters.
`email`	Body	String	No	The person's email address.
`partition`	Body	Integer	No	The ID of the partition that this person should be associated with.
`enabled`	Body	Boolean	No	Whether rules should be processed for this person. The default value is `true`.
`activeDate`	Body	String	No	The date to start processing rules for this person. This is formatted as `YYYY-MM-DDTHH:mm:ss`.
`expireDate`	Body	String	No	The date to stop processing rules for this person. This is formatted as `YYYY-MM-DDTHH:mm:ss`.
`pin`	Body	String	No	The person's PIN code. Possible values include a string of digits or `null`.
`duressPin`	Body	String	No	The person's duress PIN code. Possible values include a string of digits or `null`.
`customAttributes`	Body	Object	No	An object containing custom field values for this person.
`metadata`	Body	Object	No	A user-defined metadata object. The data storage limit is 10 KB.

Response

The response contains the ID of the newly created person object.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1
}

Retrieve a person

Request

GET https://panel-{{panel_id}}.pdk.io/api/persons/{{person_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
`panel_id`	Path	String	Yes	The cloud node serial number.
`person_id`	Path	Integer	Yes	The person ID.
`panel_token`	Header	String	Yes	A valid panel token.

tip

If you need to retrieve a person by a field other than the person ID (e.g. email address), you can preview a people report using the desired field as a filter.

Response

The response contains a person object.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1,
  "firstName": "John",
  "lastName": "Wiegand",
  "email": "john@example.com",
  "partition": 0,
  "enabled": true,
  "activeDate": "2023-07-17T09:00:00",
  "expireDate": "2023-07-21T17:00:00",
  "customAttributes": {
    "employee_id": 1234567
  },
  "metadata": {},
  "groups": [
    {
      "id": 1,
      "name": "Test Group",
      "partition": 0,
      "metadata": {}
    }
  ],
  "credentials": [
    {
      "id": 1,
      "personId": 1,
      "credentialNumber": 1234567,
      "facilityCode": null,
      "description": null,
      "types": ["card"]
    },
    {
      "id": 2,
      "personId": 1,
      "credentialNumber": null,
      "facilityCode": null,
      "description": "Pending",
      "types": ["touch", "token"]
    }
  ]
}

Update a person

Request

PUT https://panel-{{panel_id}}.pdk.io/api/persons/{{person_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "firstName": "John",
  "lastName": "Wiegand",
  "partition": 0,
  "enabled": true,
  "activeDate": null,
  "expireDate": null,
  "pin": null,
  "duressPin": null
}

Parameter	Location	Type	Required	Description
`panel_id`	Path	String	Yes	The cloud node serial number.
`person_id`	Path	Integer	Yes	The person ID.
`panel_token`	Header	String	Yes	A valid panel token.
`firstName`	Body	String	Yes	The person's first name. The maximum length is 35 characters.
`lastName`	Body	String	Yes	The person's last name. The maximum length is 35 characters.
`email`	Body	String	No	The person's email address.
`partition`	Body	Integer	Yes	The ID of the partition that this person should be associated with.
`enabled`	Body	Boolean	Yes	Whether rules should be processed for this person. The default value is `true`.
`activeDate`	Body	String	Yes	The date to start processing rules for this person. This is formatted as `YYYY-MM-DDTHH:mm:ss`.
`expireDate`	Body	String	Yes	The date to stop processing rules for this person. This is formatted as `YYYY-MM-DDTHH:mm:ss`.
`pin`	Body	String	Yes	The person's PIN code. Possible values include a string of digits or `null`.
`duressPin`	Body	String	Yes	The person's duress PIN code. Possible values include a string of digits or `null`.
`customAttributes`	Body	Object	No	An object containing custom field values for this person.
`metadata`	Body	Object	No	A user-defined metadata object. The data storage limit is 10 KB.

Response

HTTP/1.1 204 No Content

Delete a person

Request

DELETE https://panel-{{panel_id}}.pdk.io/api/persons/{{person_id}} HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
`panel_id`	Path	String	Yes	The cloud node serial number.
`person_id`	Path	Integer	Yes	The person ID.
`panel_token`	Header	String	Yes	A valid panel token.

Response

HTTP/1.1 204 No Content

List all people

Request

GET https://panel-{{panel_id}}.pdk.io/api/persons HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
`panel_id`	Path	String	Yes	The cloud node serial number.
`page`	Query	Integer	No	The zero-based page number used for pagination. The default value is 0.
`per_page`	Query	Integer	No	The number of items per page used for pagination. The default value is 10 and the maximum value is 100.
`panel_token`	Header	String	Yes	A valid panel token.

Response

The response contains an array of person objects.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 1,
    "firstName": "John",
    "lastName": "Wiegand",
    "email": "john@example.com",
    "partition": 0,
    "enabled": true,
    "activeDate": "2023-07-17T09:00:00",
    "expireDate": "2023-07-21T17:00:00",
    "customAttributes": {
      "employee_id": 1234567
    },
    "metadata": {},
    "groups": [
      {
        "id": 1,
        "name": "Test Group",
        "partition": 0,
        "metadata": {}
      }
    ],
    "credentials": [
      {
        "id": 1,
        "personId": 1,
        "credentialNumber": 1234567,
        "facilityCode": null,
        "description": null,
        "types": ["card"]
      },
      {
        "id": 2,
        "personId": 1,
        "credentialNumber": null,
        "facilityCode": null,
        "description": "Pending",
        "types": ["touch", "token"]
      }
    ]
  }
]

List all people in a group

Request

GET https://panel-{{panel_id}}.pdk.io/api/groups/{{group_id}}/persons HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
`panel_id`	Path	String	Yes	The cloud node serial number.
`group_id`	Path	Integer	Yes	The group ID.
`panel_token`	Header	String	Yes	A valid panel token.

Response

The response contains an array of person objects.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 1,
    "firstName": "John",
    "lastName": "Wiegand",
    "email": "john@example.com",
    "partition": 0,
    "enabled": true,
    "activeDate": "2023-07-17T09:00:00",
    "expireDate": "2023-07-21T17:00:00",
    "customAttributes": {
      "employee_id": 1234567
    },
    "metadata": {},
    "groups": [
      {
        "id": 1,
        "name": "Test Group",
        "partition": 0,
        "metadata": {}
      }
    ],
    "credentials": [
      {
        "id": 1,
        "personId": 1,
        "credentialNumber": 1234567,
        "facilityCode": null,
        "description": null,
        "types": ["card"]
      },
      {
        "id": 2,
        "personId": 1,
        "credentialNumber": null,
        "facilityCode": null,
        "description": "Pending",
        "types": ["touch", "token"]
      }
    ]
  }
]

List all entities for many people

This endpoint allows you to retrieve the groups, devices, rules, and floor groups associated with many people. For users familiar with Windows environments, this is similar to a resultant set of policy (RSOP) report.

Request

GET https://panel-{{panel_id}}.pdk.io/api/rsop/persons?ids=1,2,3 HTTP/1.1
Authorization: Bearer {{panel_token}}

Parameter	Location	Type	Required	Description
`panel_id`	Path	String	Yes	The cloud node serial number.
`ids`	Query	String	Yes	A comma-delimited list of person IDs.
`panel_token`	Header	String	Yes	A valid panel token.

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "date": "2023-07-19T13:03:26-07:00",
  "persons": [
    {
      "id": 1,
      "enabled": true,
      "groups": [
        {
          "id": 1,
          "name": "Test Group"
        }
      ],
      "doors": [
        {
          "id": 1,
          "activeRuleId": 1,
          "allowed": true,
          "name": "Test Device 1",
          "created": "2023-07-17 14:42:01",
          "type": "primaryReader",
          "publicIcon": "swingingDoor",
          "readerType": null,
          "securedReadsOnly": false,
          "supportBleCredentials": true,
          "readerSerialNumber": "032500000001773C"
        }
      ],
      "rules": [
        {
          "id": 1,
          "type": "door",
          "active": true,
          "allow": true,
          "authenticationPolicy": "cardOrPin",
          "startTime": "00:00",
          "stopTime": "24:00",
          "recurring": ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]
        },
        {
          "id": 2,
          "type": "elevator",
          "active": true,
          "authenticationPolicy": "cardOrPin",
          "startTime": "00:00",
          "stopTime": "24:00",
          "recurring": ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]
        }
      ],
      "floorGroups": [
        {
          "id": 1,
          "activeRuleId": 2,
          "allowed": true,
          "name": "Test Floor Group",
          "readerPort": {
            "id": 2,
            "name": "Test Device 2",
            "type": "elevatorReader"
          },
          "floors": [
            {
              "id": 3,
              "name": "Test Device 3",
              "type": "floorRelay"
            }
          ]
        }
      ]
    }
  ]
}

Property	Type	Description
`date`	String	An ISO 8601 timestamp representing the current time.
`persons`	Object[]	An array of people and their associated entities.
`persons.id`	Integer	The person ID.
`persons.enabled`	Boolean	Whether the person is enabled.
`persons.doors`	Object[]	An array of device objects representing the devices associated with the person.
`persons.floorGroups`	Object[]	An array of floor group objects representing the floor groups associated with the person.
`persons.groups`	Object[]	An array of group objects representing the groups associated with the person.
`persons.rules`	Object[]	An array of rule objects representing the rules associated with the person.

Update a person's photo

Request

PUT https://panel-{{panel_id}}.pdk.io/api/persons/{{person_id}}/photo HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHgAAAB4CAAAAAAcD2kOAAABZklEQVR4Ae3XAYnDMBTG8RqogBqIgRqogBiYgRiogBqYgRiIgBh4Bj5Rd13yIAs5uHHrGwffH2DNI+MH3cLWCR+KMGHChAkTJkz4tQgTJkyYMGHChAkTJkyYcIqDZDAXlOQevqtLiYPSr+B1GhQH84iztOnaHQDiNGi9AA7txCUrWF1tsYJ7JvwFvq2PlvqeUlJ4qYMyq5/vFoI7X2dBWktTu/v2wnHSm9jfiYAmKXvu53X29aI0dbvfC8enG5kTbGEHzRiednNY9BQd+XJ4DaUDZ27S3C5Xwv3RvLcjL3YwfDubkx2M0MtWMHJYmul1sB/8xKbgVM4mx6m1Kx2tYcjyIRjeFJZtU8qZwar5fF4d5TzhGrj/I7DXQxT0a+0vg9tinrvJnG1g6UcHbGBgn5v1fMAMhuxOlz7jLXCOj6D9+AiTyxMMnitbMp8WCRMmTJgwYcKECRMmTJgwYcKECRMmTPhfwV9kH2srWmFAYQAAAABJRU5ErkJggg=="
}

Parameter	Location	Type	Required	Description
`panel_id`	Path	String	Yes	The cloud node serial number.
`person_id`	Path	Integer	Yes	The person ID.
`panel_token`	Header	String	Yes	A valid panel token.
`base64`	Body	String	Yes	The photo encoded as a data URL.

Response

HTTP/1.1 204 No Content

Preview a people file import

Request

POST https://panel-{{panel_id}}.pdk.io/api/persons/import/preview HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json
Want-Digest: sha-265

{
  "csv": "First Name,Last Name\nJohn, Wiegand\nJames, Maxwell\nMichael, Faraday"
}

Parameter	Location	Type	Required	Description
`panel_id`	Path	String	Yes	The cloud node serial number.
`panel_token`	Header	String	Yes	A valid panel token.
`csv`	Body	String	Yes	A CSV string containing a list of people to be imported. A CSV template can be downloaded here.
`partition`	Body	Integer	No	The partition ID.
`upsert`	Body	Boolean	No	Whether the import should update or delete existing records.

info

Including the Want-Digest header in the request will produce a Digest header in the response. The value provided in the Digest header will be required if conflicts need to be resolved when importing people from a file.

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "toBeCreated": 3,
  "toBeUpdated": 0,
  "toBeDeleted": 0,
  "conflicts": [
    {
      "line": 2,
      "firstName": "John",
      "lastName": "Wiegand",
      "matches": [
        {
          "id": 1,
          "firstName": "John",
          "lastName": "Wiegand"
        }
      ]
    }
  ]
}

Property	Type	Description
`toBeCreated`	Integer	The number of people that would be created by this import.
`toBeUpdated`	Integer	The number of people that would be updated by this import.
`toBeDeleted`	Integer	The number of people that would be deleted by this import.
`conflicts`	Object[]	A list of conflicts that will need to be resolved when executing this import.
`conflicts.line`	Integer	The line number of the conflict.
`conflicts.id`	Integer	The ID of the person associated with the conflict.
`conflicts.firstName`	String	The first name of the person associated with the conflict.
`conflicts.lastName`	String	The last name of the person associated with the conflict.
`conflicts.matches`	Object[]	An array of conflicting person objects. Note that only the `id`, `firstName`, and `lastName` properties are included.

Import people from a file

tip

This endpoint is intended for one-time import operations (e.g. importing records from an old access control system). Ongoing data synchronization should be implemented using individual requests, which are more efficient and allow for more granular error handling.

Request

POST https://panel-{{panel_id}}.pdk.io/api/persons/import HTTP/1.1
Authorization: Bearer {{panel_token}}
Digest: {{digest}}
Content-Type: application/json

{
  "csv": "First Name,Last Name\nJohn, Wiegand\nJames, Maxwell\nMichael, Faraday",
  "resolutions": [
    {
      "line": 2,
      "decision": "skip"
    }
  ]
}

Parameter	Location	Type	Required	Description
`panel_id`	Path	String	Yes	The cloud node serial number.
`panel_token`	Header	String	Yes	A valid panel token.
`digest`	Header	String	Sometimes	The digest value obtained from the `Digest` header in the response of the preview a people file import endpoint. This is required if the import has conflicts that need to be resolved.
`csv`	Body	String	Yes	A CSV string containing a list of people to be imported. A CSV template can be downloaded here.
`resolutions`	Body	Object[]	Sometimes	An array of objects describing how individual conflicts should be handled. This is required if the import has conflicts that need to be resolved.
`resolutions.line`	Body	Integer	Yes	The line number of the conflict.
`resolutions.decision`	Body	String	Yes	How the conflict should be handled. Possible values include `create`, `update`, `delete`, and `skip`.
`partition`	Body	Integer	No	The partition ID.
`upsert`	Body	Boolean	No	Whether the import should update or delete existing records.

Response

The response contains an array of person objects representing the people that were created or updated.

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 1,
    "firstName": "John",
    "lastName": "Wiegand",
    ...
  },
  {
    "id": 2,
    "firstName": "James",
    "lastName": "Maxwell",
    ...
  },
  {
    "id": 3,
    "firstName": "Michael",
    "lastName": "Faraday",
    ...
  }
]

Delete many people

Request

POST https://panel-{{panel_id}}.pdk.io/api/persons/bulk-delete HTTP/1.1
Authorization: Bearer {{panel_token}}
Content-Type: application/json

{
  "persons": [1, 2, 3]
}

Parameter	Location	Type	Required	Description
`panel_id`	Path	String	Yes	The cloud node serial number.
`panel_token`	Header	String	Yes	A valid panel token.
`persons`	Body	Integer[]	Yes	A list of person IDs representing people who should be deleted.

Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "deleted": [1, 2, 3]
}

Property	Type	Description
`deleted`	Integer[]	A list of person IDs representing people who were deleted.

Introduction​

The person object​

Basic Endpoints​

Create a person​

Request

Response

Retrieve a person​

Request

Response

Update a person​

Request

Response

Delete a person​

Request

Response

List all people​

Request

Response

List all people in a group​

Request

Response

List all entities for many people​

Request

Response

Update a person's photo​

Request

Response

Preview a people file import​

Request

Response

Import people from a file​

Request

Response

Delete many people​

Request

Response

Introduction

The person object

Basic Endpoints

Create a person

Retrieve a person

Update a person

Delete a person

List all people

List all people in a group

List all entities for many people

Update a person's photo

Preview a people file import

Import people from a file

Delete many people