Contacts¶

GET/Owners/{ownerAccountId}/Contacts

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

PUT/Owners/{ownerAccountId}/Contacts

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

DELETE/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 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"
}

Create Contact¶

PUT/Owners/{ownerAccountId}/Contacts

Creates a new contact under the specified owner account.

Scope¶

write:core:entities

Parameters¶

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

Body¶

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

or

{
  "ipId": "1",
  "ipUserId": "1"
}

Info

The email field is required in the first option, both ipId and ipUserId are required in the second option. The second option is only required for users originating from external identity providers. The e-mail-based approach is primarily targeting users of the official Tapkey app.

Warning

It is not possible to mix these options. Passing email and either ipId, ipUserId or both will fail.

Response¶

200 OK

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

or

{
  "id": "1",
  "ipId": "1",
  "ipUserId": "1",
  "ownerId": "1",
  "email": "null"
}

In case email or ipId/ipUserId already exists, the operation will return:

400 A Contact with this data already exists for this owner account.

{
  "ErrorMessage": "A Contact with this data already exists for this owner account."
}

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"
  }
]

Delete Contact¶

DELETE/Owners/{ownerAccountId}/Contacts/{id}

Delete the specified contact.

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.

Response¶

204 OK

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 implicitly as a side effect.

The rclClassStates array contains the updated information of the revocation lists after the revocation process has started, such as: the current size of the list or the maximum number of entries it can hold.

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
    }
  }
]

Grant State¶

For more information about the process of revoking grants, and how a the active and state properties reflect the state of a grant's revocation, visit the Revoking Access guide.