Creating a Key Request

Once you have verified that the user has Unloc enabled Locks at the target location, you can initiate a Key Request creation. To do so, send a POST request to:

https://api.unloc.app/v1/partners/Your_Service_Provider_ID/key-requests

Inside the request body you have to specify the following:

  • receiverMsn: The mobile phone number of the user (using the E.164 format)
  • keyStart: The date and time the key will begin being valid from (using the ISO-8601 format)
  • keyEnd: The date and time when the key will expire (using the ISO-8601 format)
  • message: A message to be displayed to the user when they receive the request. This is a great place to give more information about the request to the user: "Your package delivery" or "Your Zalando package will be delivered by FedEx"
  • keyDeliveryAddressDescription: A description about the delivery address. This is visible to the user

Your request should look something like this:

curl --location --request POST '<<api_url>>/v1/partners/<<service_provider_id>>/key-requests' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <<service_provider_api_key>>' \
--data-raw '{
    "keyStart": "2021-01-01T19:48:00.000Z",
    "keyEnd": "2022-01-01T20:48:00.000Z",
    "message": "Your package delivery",
    "receiverMsn": "+47666555444",
    "keyDeliveryAddressDescription": "Home"
}'

A successful response will contain the keyRequestId:

{
    "id": "<<key_request_id>>"
}

You can use this keyRequestId to later check the request status (to verify if the user has approved the request or not) and the Keys associated with it.


What’s Next

Since the user may take a while to approve the Key Request, it's important to check when it status changes. The next step will cover just that:

Did this page help you?