Contacts

GET/Owners/{ownerAccountId}/Contacts

POST/Owners/{ownerAccountId}/Contacts

GET/Owners/{ownerAccountId}/Contacts/{id}

PATCH/Owners/{ownerAccountId}/Contacts/{id}

GET/Owners/{ownerAccountId}/Contacts/{id}/Grants

POST/Owners/{ownerAccountId}/Contacts/{id}/RevokeGrants

Get list of contacts

GET/Owners/{ownerAccountId}/Contacts

Get a list of this owner's contacts.

Scope

read:core:entities

Parameters

Name	Type	Location	Description
ownerAccountId	string	path	The owner account to get contacts for.

Response

200 OK

[
  {
    "id": "1",
    "ownerId": "1",
    "comment": "A comment describing this contact.",
    "email": "user1@tapkey.com",
    "title": "User One"
  },
  {
    "id": "2",
    "ownerId": "1",
    "comment": "A comment describing this contact.",
    "email": "user2@tapkey.com",
    "title": null
  }
]

Get or create contact by email

POST/Owners/{ownerAccountId}/Contacts

Retrieve contacts with the given email address or, if none exists, create a new one.

Queries the given owner’s contact with the given email address. If the contact doesn’t exist, a new contact is created, linking the User with the given email address. If the user doesn’t exist, the Contact is still created and can be used for assigning Grants.

Scope

write:core:entities

Parameters

Name	Type	Location	Description
ownerAccountId	string	path	The owner account to get contacts for.

Body

{
  "email": "user1@tapkey.com"
}

Response

200 OK

[
  {
    "id": "1",
    "ownerId": "1",
    "comment": "A comment describing this contact.",
    "email": "user1@tapkey.com",
    "title": "User One"
  }
]

Get contact by ID

GET/Owners/{ownerAccountId}/Contacts/{id}

Get the specified Contact.

Scope

read:core:entities

Parameters

Name	Type	Location	Description
ownerAccountId	string	path	The owner account to get contacts for.
id	string	path	The contact's ID.

Response

200 OK

{
  "id": "1",
  "ownerId": "1",
  "comment": "A comment describing this contact.",
  "email": "user1@tapkey.com",
  "title": "User One"
}

Patch contact

PATCH/Owners/{ownerAccountId}/Contacts/{id}

Patch the specified Contact.

The following properties can be patched:

• comment
• title

Scope

write:core:entities

Parameters

Name	Type	Location	Description
ownerAccountId	string	path	The owner account to get contacts for.
id	string	path	The contact's ID.

Body

{
  "comment": "A new comment describing this contact.",
  "title": "User New"
}

Response

200 OK

[
  {
    "id": "1",
    "ownerId": "1",
    "comment": "A new comment describing this contact.",
    "email": "user1@tapkey.com",
    "title": "User New"
  }
]

Get grants for contact

GET/Owners/{ownerAccountId}/Contacts/{id}/Grants

Get a queryable list of Grants assigned to the given Contact.

Scope

read:grants

Parameters

Tip

The returned list can be filtered using OData query parameters.

Name	Type	Location	Description
ownerAccountId	string	path	The owner account to get contacts for.
id	string	path	The contact's ID.

Response

200 OK

[
  {
    "contact": {
      "id": "1",
      "ownerId": "1",
      "comment": "A new comment describing this contact.",
      "email": "user1@tapkey.com",
      "title": "User One"
    },
    "boundCard": null,
    "boundLock": {
      "lockType": {
        "id": "TK.Td30",
        "manufacturerId": 1,
        "modelName": "Td30",
        "supportedTechnologies": [
          "nfc",
          "ble"
        ]
      },
      "supportedFeatures": {
        "timeRestrictionIcalSupport": "Supported"
      },
      "id": "1",
      "physicalLockId": "AAChsgq2",
      "lockTypeId": "TK.Td30",
      "ownerAccountId": "1",
      "bindDate": "2018-12-12T12:00:00.000Z",
      "title": "Entrance Door",
      "description": null,
      "rclSerialNo": 1,
      "rclDate": "2018-12-12T12:00:01.000Z"
    },
    "id": "1",
    "boundLockId": "1",
    "contactId": "1",
    "validFrom": null,
    "validBefore": null,
    "timeRestrictionIcal": null,
    "state": "Ok",
    "active": true,
    "boundCardId": null
  }
]

Revoke contact's grants

POST/Owners/{ownerAccountId}/Contacts/{id}/RevokeGrants

Revoke all Grants issued to the given contact.

This operation will initiate the process of revoking all Grants issued to a Contact (i.e. a smartphone-based Grant). All keys issued for the Contact's Grants will be added to the revocation list (RCL) and the revocation process is started.

As the revocation list has a limited capacity, revoking too many keys for an individual lock can cause the revocation list capacity to be exceeded. In this case, keys issued before the oldest revoked key contained in the revocation list will be implicitly revoked too. In this case, keys implicitly revoked as side effects will be renewed automatically as soon as the affected smartphone is online. Thus, users of affected smartphone most likely won’t recognize the renewal process.

A list of Grants, for which keys have been issued that are being implicitly revoked as a side effect is returned by this operation. By setting the dryRun parameter to true, the effect can be queried from the server without actually executing the revocation. This way, the user can be informed about side effects upfront.

Scope

write:grants

Parameters

Name	Type	Location	Description
ownerAccountId	string	path	The owner account to get contacts for.
id	string	path	The contact's ID.
dryRun	boolean	query	If true, this operation will not actually execute the revocation but only return information about the potential effect. This can be used to inform the user about potential side effects a revocation could have.

Response

The operation returns an array of objects of the following type:

{
    "dryRun": false,
    "grantRevoked": {...},
    "grantsAffectedAsSideEffect": [],
    "rclState": {
      "rclClassStates": null
    }
}

where grantRevoked contains the Grant and grantsAffectedAsSideEffect holds a list of Grants that have been revoked implicitely as a side effect.

Exemplary Response

200 OK

[
  {
    "dryRun": false,
    "grantRevoked": {
      "contact": {
        "id": "1",
        "ownerId": "1",
        "comment": "A new comment describing this contact.",
        "email": "user1@tapkey.com",
        "title": "User One"
      },
      "boundCard": null,
      "boundLock": {
        "lockType": {
          "id": "TK.Td30",
          "manufacturerId": 1,
          "modelName": "Td30",
          "supportedTechnologies": [
            "nfc",
            "ble"
          ]
        },
        "supportedFeatures": {
          "timeRestrictionIcalSupport": "Supported"
        },
        "id": "1",
        "physicalLockId": "AAChsgq2",
        "lockTypeId": "TK.Td30",
        "ownerAccountId": "1",
        "bindDate": "2018-12-12T12:00:00.000Z",
        "title": "Entrance Door",
        "description": null,
        "rclSerialNo": 1,
        "rclDate": "2018-12-12T12:00:01.000Z"
      },
      "id": "1",
      "boundLockId": "1",
      "contactId": "1",
      "validFrom": null,
      "validBefore": null,
      "timeRestrictionIcal": null,
      "state": "RevocationPending",
      "active": false,
      "boundCardId": null
    },
    "grantsAffectedAsSideEffect": [],
    "rclState": {
      "rclClassStates": null
    }
  }
]