NAV Navbar
Logo
shell

Introduction

Welcome to the CANDY HOUSE Developer Site! We use RESTful API to provide basic manipulation of Sesame, including:

Many new functions are still under development and will be coming soon, so stay tuned!

Please note that in order to enable API for your Sesame, you must be the owner of Sesame and be a part of our iOS Beta Testing Program. You will need to install Virtual Station on a spare iOS device and install TestFlight Sesame on your iPhone. Be sure to follow these instructions for setting up Virtual Station and enabling cloud integration in your Sesame app.

If you would like to suggest changes to the documentation or if you find any bugs, please feel free to contact us.

Versioning

The current API version is v1, so every endpoint should be prefixed with:

https://api.candyhouse.co/v1

Parameters

Pass parameter in json body

curl -H "Content-Type: application/json" \
    -X POST -d '{"param1":"value1", "param2":"value2"}'

Pass parameter in query strings

curl "https://api.candyhouse.co/v1/endpoint?param1=value1&param2=value2"

Always pass parameters in json body for POST and query strings for GET.

Timestamp

Timestamp examples

2017-01-02T03:04:05Z
2017-01-02T03:04:05.789Z

We use ISO8601 for the timestamp format.

Authentication

curl -H "X-Authorization: YOUR_AUTH_TOKEN"

After successfully logging in, you will get an auth token. Each login-required request needs to have the auth token set in the X-Authorization header.

Login API

curl -H "Content-Type: application/json" \
    -X POST -d '{"email":"abc@i-lovecandyhouse.co", "password":"super-strong-password"}' \
    https://api.candyhouse.co/v1/accounts/login

{
  "authorization": "d015cf1353d21a14f392835bceb56d53649e447e3aebe440cef9d"
}

POST /accounts/login

Post Body

Parameter Type Description
email string
(required) User email
password string
(required) User password

Response Fields

Parameter Type Description
authorization string
Login auth token

Expiration

Sesame API

Get Sesame list

curl -H "X-Authorization: YOUR_AUTH_TOKEN" \
  https://api.candyhouse.co/v1/sesames
  {
    "sesames": [
      {
        "device_id": "ABC1234567",
        "nickname": "Front door",
        "is_unlocked": true,
        "api_enabled": true,
        "battery": 100
      }, {
        "device_id": "DEF7654321",
        "nickname": "Back door",
        "is_unlocked": false,
        "api_enabled": false,
        "battery": 80
      }
    ]
  }

GET /sesames

Response Fields

Parameter Type Description
sesames array Array of Sesames
sesames[i].device_id string
Sesame ID
sesames[i].nickname string
Sesame nickname
sesames[i].is_unlocked boolean
Sesame is unlocked
sesames[i].api_enabled boolean
Sesame is API-enabled (Sesame must be paired with Virtual Station or Wi-Fi Access Point and have API enabled in app)
sesames[i].battery integer Sesame battery status

Get Sesame

curl -H "X-Authorization: YOUR_AUTH_TOKEN" \
  https://api.candyhouse.co/v1/sesames/ABCD12345
  {
    "nickname": "Front door",
    "is_unlocked": true,
    "api_enabled": true,
    "battery": 100
  }

GET /sesames/{sesameId}

Response Fields

Parameter Type Description
nickname string
Sesame nickname
is_unlocked boolean
Sesame is unlocked
api_enabled boolean
Sesame is API-enabled (Sesame must be paired with Virtual Station or Wi-Fi Access Point and have API enabled in app)
battery integer Sesame battery status

Control Sesame

curl -H "X-Authorization: YOUR_AUTH_TOKEN" \
    -H "Content-Type: application/json" \
    -X POST -d '{"type":"lock"}' \
    https://api.candyhouse.co/v1/sesames/ABCD12345/control

# 204 No content
''

POST /sesames/{sesameId}/control

Post Body

Parameter Type Description
type string
(required) lock or unlock

Response Types

Code Title Description
200 OK Request was successful
204 No content Request was successful; no response received
400 Bad request Bad request
401 Unauthorized Your authorization header is missing or expired
403 Forbidden You don’t have permission to do this
404 Not found The resource does not exist
50X Internal Server Error Oops, please notify CANDY HOUSE of server error

Errors

Check the tables below for descriptions of each error code:

General Bad Request (400)

Error Code Description
10000 Required field cannot be empty
10001 Email is invalid
10002 Wrong email or password
10005 Wrong control type; control must be “lock” or “unlock”
11002 Sesame not found

Unauthorized (401)

Error Code Description
20000 Missing auth token
20001 Wrong auth token
20002 Auth token expired
20003 Auth token expired due to password change
20004 Auth user account has been deleted

Permission Error (403)

Error Code Description
30000 Owner permission required
31000 Account email has not been verified
31001 Account is locked
32000 Cloud API not enabled

Server Error (500)

Error Code Description
5xxxx Internal server failure

Third-Party Libraries & Plugins

We love seeing what awesome things Sesame users are doing with our cloud API!

Have something to share? Email us and we’ll be happy to add it to the list!

Sesame.NET by Ben Randall

“A .NET client for the Sesame API.”

pysesame by trisk

“Python API for controlling Sesame smart locks made by CANDY HOUSE, Inc.”

QSesame by Brendan

“QSesame is a Homebridge plugin that allows you to control Sesame smart locks with Siri by integrating with HomeKit.”

Sesame Platform by Home Assistant

“The sesame platform allows you to control your Sesame smart locks made by CANDY HOUSE, Inc.”