---
updatedAt: 2025-08-11T18:18:17.000Z
agentTools:
projectIndex: https://docs.keycafe.com/llms.txt
---
# Create Access
Create an access with a POST request to the endpoint.
# Sample Post Body Request
The post body should contain the necessary data to create the access as a JSON object:
```json json
{
"user": {
"id" : 123456,
"email": "user@yourdomain.com",
"mobile": "16042656073"
},
"key": { "id" : 123456, "serialNumber": "XXXXX" },
"accessStartDate": "2025-04-21",
"accessStartTime": "12:45",
"accessEndDate": "2025-04-23",
"accessEndTime": "12:45",
"timeZone": "America/Vancouver",
"name": "Bob S.",
"returnReminder": false,
"suppressGuestNotifications": false,
"locale": "en",
"allowSetup": false
}
```
# Suppressing Guest Communications
If you prefer not to have Keycafe send any messages to your guests, set the suppressGuestNotifications property to true. In this case, you must provide the guest with the bookingCode and checkinLink yourself through your own communication channels.
* The booking code can be entered directly into the SmartBox screen by the guest.
* The check-in link offers a guided mobile experience for key pickup and drop-off.
These values allow your guest to complete their key exchange without any communication from Keycafe.
# Offline Key Exchange Best Practice
To ensure a seamless key exchange experience with [Offline Mode](https://support.keycafe.com/hc/en-us/articles/360044029571-Battery-Power-and-Offline-Mode#h_01J818F8BXYJHYEHKBR0A45HSX), it is recommended to communicate booking codes to users in advance or keep them available locally in your app. This approach avoids relying on API availability to retrieve and display booking codes during the key exchange, providing a reliable experience even in offline scenarios.
# Date Formats
There are two methods for specifying access dates.
* ISO 8601 Format (Deprecated)
* Separated date, time and timezone components.
### ISO 8601 Format (Deprecated)
A single timestamp (e.g., "2024-04-22T12:45:00Z"). This method is deprecated due inconsistent support for "local" times.
### Separated Components (Recommended)
This approach breaks the access window into separate date and time fields:
Use individual fields:
* accessStartDate, accessStartTime
* accessEndDate, accessEndTime
* timeZone (optional)
This offers more flexibility and predictable local time handling.
### Time Zone Behavior
* Omitting date/time data will result in an ongoing access.
* If time zone is omitted, the provided times are interpreted as local to the key’s current location where the key is stored. For example: if the location is in New York, then an accessEndTime of 00:00 ends at midnight in New York time.
* If time zone is specified, the times are first interpreted in the given time zone and then converted to the key’s local time. For example, an access window ending at 00:00 in America/Vancouver will end at 03:00 in America/New\_York.
# OpenAPI definition
```json
{
"openapi": "3.0.3",
"info": {
"title": "Keycafe API",
"version": "0"
},
"x-explorer-enabled": true,
"x-proxy-enabled": true,
"x-samples-languages": [
"shell",
"python",
"go"
],
"servers": [
{
"url": "https://www.keycafe.com/"
}
],
"components": {
"securitySchemes": {
"BasicAuth": {
"type": "http",
"scheme": "basic"
}
}
},
"security": [
{
"BasicAuth": []
}
],
"paths": {
"/v0/access": {
"post": {
"tags": [
"Access"
],
"summary": "Create Access",
"description": "Create an access with a POST request to the endpoint.",
"operationId": "create-access",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"key"
],
"properties": {
"user": {
"type": "object",
"description": "The user being give access. Only the ID property is necessary if it's an existing user. Otherwise, an email address or mobile number can be included to invite a new user.",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"x-readme-id": "1.0"
},
"email": {
"type": "string",
"x-readme-id": "1.1"
},
"mobile": {
"type": "string",
"x-readme-id": "1.2"
}
},
"x-readme-id": "0.0"
},
"key": {
"type": "object",
"description": "The key for which access is being given. Only one of the ID or serialNumber property is necessary.",
"properties": {
"id": {
"type": "integer",
"format": "int64",
"description": "Unique identification number ",
"x-readme-id": "1.0"
},
"serialNumber": {
"type": "string",
"description": "Unique serial numner",
"x-readme-id": "1.1"
}
},
"x-readme-id": "0.1"
},
"accessStartDate": {
"type": "string",
"description": "The access start date . See the discussion of date formats below. Example: 2025-07-21",
"x-readme-id": "0.2"
},
"accessStartTime": {
"type": "string",
"description": "The access start time . See the discussion of date formats below. Example:12:45",
"x-readme-id": "0.3"
},
"accessEndDate": {
"type": "string",
"description": "The access end date . See the discussion of date formats below. Example: 2025-07-23",
"x-readme-id": "0.4"
},
"accessEndTime": {
"type": "string",
"description": "The access end time. See the discussion of date formats below. Example: 12:45",
"x-readme-id": "0.5"
},
"timeZone": {
"type": "string",
"description": "The access time zone. See the discussion of date formats below. Example: America/Vancouver",
"x-readme-id": "0.6"
},
"name": {
"type": "string",
"description": "The visitor's name. Required if no user information is specified. In this case, because the user's contact information is not available, you will be responsible for communicating the booking code, booking URL, and instructions to your guest. Example: Paul",
"x-readme-id": "0.7"
},
"returnReminder": {
"type": "boolean",
"default": false,
"description": "Default false. Whether the guest should be sent a reminder to return the key after their visit. Example: False",
"x-readme-id": "0.8"
},
"suppressGuestNotifications": {
"type": "boolean",
"default": false,
"description": "Default false. If true, prevents any access notifications from being sent to the guest. Example: False",
"x-readme-id": "0.9"
},
"locale": {
"type": "string",
"description": "The locale to use to send notifications to the guest. Supported values are en, fr, ja, es, nl, it, pt. Example: en",
"x-readme-id": "0.10"
},
"allowSetup": {
"type": "boolean",
"default": false,
"description": "Default false. If true, the access recipient will be able to attach a fob to the key. Example: false",
"x-readme-id": "0.11"
},
"startDate": {
"type": "string",
"format": "date",
"description": "`Deprecated`. See the discussion of date formats below. The start date of the access, in ISO 8601 format without milliseconds. If both startDate and endDate are omitted, the access is considered ongoing. Example: 2025-07-21T12:45:00Z",
"x-readme-id": "0.12"
},
"endDate": {
"type": "string",
"format": "date",
"description": "`Deprecated`. See the discussion of date formats below. The end date of the access, in ISO 8601 format without milliseconds. If both startDate and endDate are omitted, the access is considered ongoing. Example: 2025-07-23T17:45:00Z",
"x-readme-id": "0.13"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Access record successfully created.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"description": "Unique identifier for the newly created access record.",
"example": 1234567
},
"user": {
"type": "object",
"description": "The user to whom the access was granted.",
"properties": {
"id": {
"type": "integer",
"description": "Unique identifier of the user.",
"example": 123456
},
"email": {
"type": "string",
"description": "Email address of the user.",
"example": "user@yourdomain.com"
},
"mobile": {
"type": "string",
"description": "Mobile phone number of the user.",
"example": 16042656073
},
"firstName": {
"type": "string",
"description": "User’s first name.",
"example": "Bob"
},
"lastName": {
"type": "string",
"description": "User’s last name.",
"example": "Smith"
}
}
},
"key": {
"type": "object",
"description": "Key that is being shared or accessed.",
"properties": {
"id": {
"type": "integer",
"description": "Unique identifier of the key.",
"example": 123456
},
"serialNumber": {
"type": "string",
"description": "Serial number of the key.",
"example": "XXXXX"
}
}
},
"accessStartDate": {
"type": "string",
"description": "Start date of the access (YYYY-MM-DD).",
"example": "2025-07-21"
},
"accessStartTime": {
"type": "string",
"description": "Start time of the access (HH:mm).",
"example": "12:45"
},
"accessEndDate": {
"type": "string",
"description": "End date of the access (YYYY-MM-DD).",
"example": "2025-07-23"
},
"accessEndTime": {
"type": "string",
"description": "End time of the access (HH:mm).",
"example": "12:45"
},
"timeZone": {
"type": "string",
"description": "Time zone for the access period.",
"example": "America/Vancouver"
},
"name": {
"type": "string",
"description": "Display name for the access record (typically guest name).",
"example": "Bob S."
},
"returnReminder": {
"type": "boolean",
"description": "Whether a reminder should be sent for key return.",
"example": false
},
"suppressGuestNotifications": {
"type": "boolean",
"description": "Whether to suppress email/SMS notifications to the guest.",
"example": false
},
"bookingCode": {
"type": "string",
"description": "Code associated with the booking or access.",
"example": 12345678
},
"checkinLink": {
"type": "string",
"description": "Public-facing link for the guest to check in.",
"example": "https://keycafe.com/c/uI2SLoVtCWUJaiNo"
},
"locale": {
"type": "string",
"description": "Language or locale code used for communication.",
"example": "en"
},
"allowSetup": {
"type": "boolean",
"description": "Whether the guest is allowed to set up the access.",
"example": false
}
}
},
"examples": {
"Result": {
"value": "{\n \"id\": 1234567,\n \"user\": {\n \"id\" : 123456,\n \"email\": \"user@yourdomain.com\",\n \"mobile\": \"16042656073\",\n \"firstName\": \"Bob\",\n \"lastName\": \"Smith\"\n },\n \"key\": { \"id\" : 123456, \"serialNumber\": \"XXXXX\" },\n \"accessStartDate\": \"2025-07-21\",\n \"accessStartTime\": \"12:45\",\n \"accessEndDate\": \"2025-07-23\",\n \"accessEndTime\": \"12:45\",\n \"timeZone\": \"America/Vancouver\",\n \"name\": \"Bob S.\",\n \"returnReminder\": false,\n \"suppressGuestNotifications\": false,\n \"bookingCode\": \"12345678\",\n \"checkinLink\": \"https://keycafe.com/c/uI2SLoVtCWUJaiNo\",\n \"locale\": \"en\",\n \"allowSetup\": false\n}"
}
}
}
}
}
},
"deprecated": false
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": true,
"proxy-enabled": true
},
"x-readme-fauxas": true
}
```