1KEY Developers
Guides

Intercoms

Intercoms

A 1Key Intercom is the entry console at a building's door. Like a hub, it has an ID printed on its label as a Serial, 1KIC-QZRF-RDWY-DVTK, used lowercase as its ID, 1kic-qzrf-rdwy-dvtk. Every intercom's Serial starts with 1KIC, and every hub's with 1KEY. It belongs to one of your organization's sites.

An intercom is managed one of two ways, chosen when you add it:

management
1valet (the default) Connected to the building's 1Valet account: it enrolls at the door with the building's code, and its directory, codes, faces, deliveries and calls come from 1Valet. The API reads them
1key Managed here: it enrolls at the door with a code from the API, and you keep its directory, codes, cards and faces through the API. No calls, deliveries or parking

To change it, remove the intercom, factory reset it and add it again.

Intercoms have their own scopes: intercoms:read to read them, intercoms:write to add, move, rename and remove them, and intercoms:command to open the door.

Adding an intercom

Once the intercom is installed and online, add it to a site by its Serial:

curl
curl -X POST https://api.1keyplatform.dev/v1/intercoms \
  -H "Authorization: Bearer $ONEKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"serial": "1KIC-QZRF-RDWY-DVTK", "site_id": "6f1c2a9e-4b7d-4e0a-9c3f-2d8e5a1b7c40", "name": "Front door", "management": "1key"}'

Needs intercoms:write. management is 1valet when left out. Adding an intercom enrolled with 1Valet as 1key, or adding one again the other way, is 409 conflict. The Serial is accepted in any case, with or without dashes. A Serial that isn't an intercom's (1KIC-XXXX-XXXX-XXXX, with a valid check digit) is 400 invalid_request. 422 intercom_not_addable means the Serial isn't one 1Key made, or another organization has it. An intercom can be added before it's installed: it shows as not connected until it comes online. Adding an intercom your organization already has moves it to the site you name. An intercom enrolled with 1Valet is added by its enrollment: to the organization 1Key keeps for its 1Valet customer, at its building's site.

Reading intercoms

curl
curl https://api.1keyplatform.dev/v1/intercoms/1kic-qzrf-rdwy-dvtk \
  -H "Authorization: Bearer $ONEKEY_API_KEY"
json
{
  "id": "1kic-qzrf-rdwy-dvtk",
  "name": "Front door",
  "site_id": "6f1c2a9e-4b7d-4e0a-9c3f-2d8e5a1b7c40",
  "site_name": "Harbour Lofts",
  "connection": { "status": "online", "since": "2026-10-01T09:14:02Z", "last_seen_at": "2026-10-01T11:02:40Z", "stability": "stable" },
  "enrollment": {
    "state": "enrolled",
    "building_id": "0b6c1f0e-3d1a-4c55-9e57-6a2f9d1c8b11",
    "building_name": "Harbour Lofts",
    "entry_console_id": "5e2d7a90-1c4b-4f8e-a3d6-0f9b2c7e4a18",
    "entry_console_name": "Lobby entrance",
    "enrolled_at": "2026-09-30T14:02:11Z"
  },
  "door": { "opens": "local", "relay": { "port": 1, "pulse_s": 5 } },
  "power": { "source": "poe" },
  "created_at": "2026-09-30T13:58:40Z"
}

connection is a hub's connection, with the same fields. model is the hardware its latest status reports: 1002l, or virtual for the desktop virtual intercom, the intercom application running on a Mac or Windows computer (null before its first status). GET /intercoms lists them by ID, a page at a time (limit, starting_after), and takes site_id and q (part of the ID or name).

enrollment
state none: not enrolled, the intercom shows a code prompt; enrolled; ended: the building revoked it, and it prompts again
building_id, building_name the 1Valet building it enrolled into
entry_console_id, entry_console_name the entry console it is in that building
enrolled_at when it enrolled
door
opens local: the intercom's own relay opens the door; remote: the building's access controller does, when 1Valet tells it
relay for local, the relay port and how long it is pulsed, pulse_s; otherwise null

door is null until the intercom has its building's configuration. power.source is the supply it runs on, as it last reported it: dc (12 V DC), poe, both or unknown; power is null until it has reported one. firmware, network and interfaces are as for a hub. An intercom that is not your organization's returns 404, the same as one that does not exist.

GET /intercoms/{id}/uptime measures its connection as a hub's uptime: range 24h, 7d or 30d, days in its site's time zone.

Managed in 1Key

These change an intercom added with "management": "1key"; for one managed by 1Valet they answer 409 conflict. Each change reaches the intercom within seconds while it's online, and the rest when it reconnects.

Enrolling it

The intercom shows a code prompt until it's enrolled. Get its code and enter it on the intercom's screen:

curl
curl https://api.1keyplatform.dev/v1/intercoms/1kic-qzrf-rdwy-dvtk/enrollment-code \
  -H "Authorization: Bearer $ONEKEY_API_KEY"
json
{ "intercom_id": "1kic-qzrf-rdwy-dvtk", "code": "482910", "expires_at": "2026-10-27T14:00:00Z" }

A code works once, for 24 hours; reading it again gives the same code until then. POST to the same path makes a new one. DELETE /intercoms/{id}/enrollment ends the enrollment: the intercom goes back to its prompt, and its directory and codes stay here for when it enrolls again. All three need intercoms:write.

Directory

GET /intercoms/{id}/entries lists who visitors find on the intercom; POST adds one, and PATCH and DELETE /intercoms/{id}/entries/{entry_id} change and remove one.

Field
name Required, up to 100 characters
unit Optional, up to 20 characters
kind resident (the default) or concierge
sort Optional order; otherwise by name

Codes and cards

GET /intercoms/{id}/credentials lists them, with code_hint, the last two digits: a code is never returned after it's added. POST adds one; PATCH and DELETE /intercoms/{id}/credentials/{credential_id} change and remove one. A change can't set the code: remove it and add another.

Field
kind pin (the default) or card
code A pin: 4 to 10 digits. A card: its number as decimal (77771716), as facility:card for Wiegand 26-bit (18:12345), or its UID in hex (04 A2 B3 C4). It's stored as the decimal number the intercom reads
card_format Optional: decimal, wiegand26, hex, or hex_reversed for a UID exported in the other byte order
entry_id Optional: the directory entry it belongs to
label Optional
type general (the default), or disposable for one use
enabled Defaults to true
schedule Optional: starts_at, ends_at, and weekly windows in the site's time zone, as a lock user's

The same code or card twice on one intercom is 409 conflict. While the intercom is online, the cloud checks a typed code; while it's offline, the intercom checks its own copy.

Faces

A face is a credential of kind face, learned from one to three photos of a person. At the door the intercom checks that the face is a live person and matches one it holds, then applies the credential's enabled, type and schedule, online or not. Adding one needs the person's consent, and owners and admins can add one in the portal from photos or the browser's camera.

curl
curl -X POST https://api.1keyplatform.dev/v1/intercoms/1kic-qzrf-rdwy-dvtk/credentials \
  -H "Authorization: Bearer $ONEKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind": "face", "label": "Ana Ruiz", "entry_id": 23467, "consent": true, "photos": ["/9j/4AAQSkZJRg..."]}'
Field
photos 1 to 3 JPEGs, base64: the face straight on, in good light, 112 to 4,096 pixels on each side, at most 90,000 bytes in all. 640 pixels on the longer side is plenty
consent Must be true: the person agreed to their face being used to open this door. The answer records when, as consented_at

label, entry_id, type, enabled and schedule are a code's.

1Key checks each photo and computes the face's embedding from it with the intercom's face model: a set of numbers the intercom matches faces with. The intercom needn't be online. 1Key keeps only the embeddings, encrypted, and the model that made them (model); the photos aren't stored anywhere, the request log included. The answer shows template_count, one per photo. A change can't replace the face: remove it and add it again. Removing it makes the intercom forget it.

If any photo isn't good enough, nothing is added and the answer is 422 face_rejected, with each refused photo in photos:

json
{"error": {"type": "face_rejected", "message": "Not good enough to learn the face from. Photo 2: the face is too small.", "photos": [{"photo": 1, "reason": "too_small"}]}}
reason
no_face No face found
many_faces More than one face
too_small The face is too small in the photo
unclear Blurred, too dark, or turned away from the camera
unreadable Not a JPEG 1Key could read

503 face_unavailable means faces can't be learned right now: try again shortly. Photos taken by the intercom's own camera match best; a phone or webcam photo works, and two or three from slightly different angles help.

Settings

GET and PATCH /intercoms/{id}/settings: relay_port (1 to 3, or null for none) and pulse_ms; the door contact, contact_input (1 to 3, or null) and contact_normally (closed or open with the door shut); held_open_s, after which a door left open raises an alarm (needs a contact); and the screen's locale, languages and temperature_unit (c or f).

Directory and codes from 1Valet

The building's 1Valet account keeps its residents, suites and codes; 1Valet BAS tells the cloud when they change (the cloud also checks hourly), and the cloud sends them to the building's intercoms, which keep a copy for when the cloud is unreachable. Read what the cloud last pulled:

curl
curl https://api.1keyplatform.dev/v1/intercoms/1kic-qzrf-rdwy-dvtk/directory \
  -H "Authorization: Bearer $ONEKEY_API_KEY"
json
{
  "data": [
    { "suite_number": null, "name": "Front desk", "concierge": true, "listed": true },
    { "suite_number": "204", "name": "Lena Fischer", "concierge": false, "listed": true }
  ],
  "source": "1valet_bas",
  "building_name": "Harbour Lofts",
  "checked_at": "2026-10-01T11:02:00Z",
  "synced_at": "2026-10-01T11:02:00Z",
  "changed_at": "2026-10-01T09:40:12Z",
  "on_intercoms": true
}

GET /intercoms/{id}/codes answers access_codes (each code masked: one longer than 4 characters shows its last two, ••••82) and guest_codes, the guest QR codes residents create in the 1Valet app, without the QR code or its secret.

checked_at when the cloud last asked 1Valet, answered or not
synced_at when 1Valet last answered with all of it; older than checked_at while 1Valet isn't answering
changed_at when its content last changed
on_intercoms whether the building's online intercoms took this copy

Both are read-only: residents and codes are managed in 1Valet. For an intercom that isn't enrolled they are empty, with null times. Needs intercoms:read.

Moving and renaming

curl
curl -X PATCH https://api.1keyplatform.dev/v1/intercoms/1kic-qzrf-rdwy-dvtk \
  -H "Authorization: Bearer $ONEKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Main entrance", "site_id": "6f1c2a9e-4b7d-4e0a-9c3f-2d8e5a1b7c40"}'

Needs intercoms:write. Either field may be left out; "name": null clears the name.

Opening the door

curl
curl -X POST https://api.1keyplatform.dev/v1/intercoms/1kic-qzrf-rdwy-dvtk/door/unlock \
  -H "Authorization: Bearer $ONEKEY_API_KEY" \
  -H "Idempotency-Key: 4f9e2c1a-front-door"

Needs intercoms:command. The intercom opens the door the way the building is set up, its own relay or the building's controller, and answers when it has:

json
{ "intercom_id": "1kic-qzrf-rdwy-dvtk", "opened_at": "2026-10-01T11:03:02.418Z" }

An unlock expires 10 seconds after the cloud sends it, so a delayed one never opens the door late:

Status type
200 The door opened at opened_at
409 unlock_expired The intercom got the unlock after it expired. The door did not open
503 hub_offline The intercom is not connected
504 hub_timeout The intercom did not answer within 10 seconds. The door may have opened; retry with the same Idempotency-Key

With an Idempotency-Key, as for device commands, a retry gets the first answer and the intercom opens the door once. Every opening is recorded as a door.unlocked event.

The virtual concierge

A site can give its intercoms a virtual concierge: an animated character on the intercom's screen that a visitor talks with, in English, French or Spanish. It answers questions about the building (hours, amenities, directions, address, contacts, deliveries) from what you set in its profile, opens the intercom's screens for the visitor (Deliveries, Code/QR Entry, Guest Parking, the Directory), and greets residents the intercom recognises by name. With calls on, it calls a resident or the front desk from the intercom's directory once the visitor confirms who. It can't open doors, and never says units or who lives in the building. Conversations aren't recorded: no audio or transcript is kept.

Setting it up

Each site has one concierge profile. It's off until you turn it on:

curl
curl -X PATCH https://api.1keyplatform.dev/v1/sites/$SITE_ID/concierge \
  -H "Authorization: Bearer $ONEKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "persona_name": "Mia",
    "profile": {
      "info": {"en": "A 30-storey condo by the lake.", "fr": "Un condo de 30 étages au bord du lac."},
      "address": "120 Harbour St, Toronto",
      "amenities": [
        {"name": {"en": "Gym", "fr": "Gym"}, "location": "Floor 2",
         "hours": [{"days": ["mon","tue","wed","thu","fri"], "opens": "06:00", "closes": "22:00"},
                   {"days": ["sat","sun"], "opens": "08:00", "closes": "20:00"}]}
      ],
      "directions": [{"to": "Management office", "text": "Through the lobby, first door on the left."}],
      "contacts": [{"name": "Front desk", "role": "Security", "phone": "+1 416 555 0100", "hours": "24 hours"}],
      "deliveries": "Couriers leave parcels in the mailroom by the north doors, open 7 a.m. to 11 p.m."
    },
    "calls": true,
    "pronunciations": {"Ste-Catherine": "Saint Catherine"}
  }'

GET /sites/{site_id}/concierge reads it. Needs sites:write to change, sites:read to read.

Field
enabled Whether the site's intercoms offer the concierge
persona_name The name it introduces itself with
voices Its voice in each language, e.g. {"fr": "cedar"}, or a Cartesia voice ID where the concierge speaks in a building's own voice; a language left out keeps the default, which GET shows. Spanish is Mexican Spanish. When the visitor switches language, the concierge continues the conversation in that language's voice
languages The languages it speaks, from en, fr, es
style How it speaks, in a few sentences; leave out for the default (shown as default_style). It greets residents it recognises by first name, or by title and last name ("Mr Smith") when the style is formal
knowledge What it should know about the building beyond profile, as free text in its prompt (up to 8 KB): where parcels go, visitor parking, house rules
persona_bio Facts about the person the character is modelled on, shared when a visitor asks (up to 2 KB)
calls Whether it can call a resident or the front desk (the directory's concierge entries) from the intercom it's talking at. It finds the person by the name the visitor says, asks "Shall I call …?", and calls only after a yes. Off by default: it opens the Directory instead
pronunciations How to say words it gets wrong, e.g. {"Ste-Catherine": "Saint Catherine"}: at most 100
privacy_answer What it answers when asked whether it records; leave out for the default (shown as default_privacy_answer)
profile What it knows: info, address, amenities, directions, contacts, deliveries. Any text can be a string or one per language ({"en": ..., "fr": ...}). Amenity hours are lists of days (mon to sun) with opens and closes (HH:MM), in the site's time zone. At most 32 KB
daily_sessions Conversations a day across the site, from midnight at the site (default 200)
max_concurrent Conversations at once across the site (default 2)
max_session_s The longest one conversation lasts, 30 to 480 seconds (default 300)
idle_timeout_s How long it waits for the visitor before the conversation ends (default 30)
monthly_minutes Minutes of conversation a calendar month across the site, at the site (default 1000)

Each intercom's prompt

An intercom can change what its concierge is told, for an entrance that differs from the rest of the building:

curl
curl -X PATCH https://api.1keyplatform.dev/v1/intercoms/1kic-qzrf-rdwy-dvtk/concierge \
  -H "Authorization: Bearer $ONEKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"knowledge": "This is the garage entrance. The lobby is one floor up by the elevator."}'
Field
style How it speaks here, in place of the site's style
knowledge What it should know at this entrance
knowledge_mode append (default): after the site's knowledge. replace: instead of it

An empty string clears a field, and the site's applies again. The answer, and GET /intercoms/{id}/concierge, show the prompt a conversation starts with (effective.prompt, for ?language= auto, en, fr or es), the style and building knowledge in force. Whatever the site or intercom says, the concierge can't open doors, or say units or who lives in the building. Needs intercoms:write to change, intercoms:read to read.

Conversations and usage

curl
curl "https://api.1keyplatform.dev/v1/sites/$SITE_ID/concierge/usage?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $ONEKEY_API_KEY"

The site's conversations by day at the site: how many, their seconds, the audio each way, the model's tokens, the characters spoken in a building's own voice (speech_characters), the cost in USD, and how quickly the concierge answered (latency: the 50th and 95th percentile milliseconds from the end of the visitor's speech to the concierge's first audio, as the cloud and as the intercom measured it). At most 92 days; the last 30 by default. GET /sites/{site_id}/concierge/sessions lists the conversations, newest first, with how each ended, its turns and interruptions, and how quickly the concierge answered. Needs sites:read.

Trying it without an intercom

curl
curl -X POST https://api.1keyplatform.dev/v1/intercoms/1kic-qzrf-rdwy-dvtk/concierge/sessions \
  -H "Authorization: Bearer $ONEKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"language": "en"}'

Starts a conversation as the intercom would when a visitor wakes the concierge, and answers 201 with the gateway's url and a token to connect with in the next 60 seconds. It counts toward the site's limits, and ends a conversation the intercom has open. Needs intercoms:command.

Status type
409 concierge_unavailable The intercom isn't at a site, or the site's concierge isn't enabled
429 quota_exceeded The site has had its daily_sessions today, or its monthly_minutes this month
503 concierge_busy The site has max_concurrent conversations open; try again shortly

Events

curl
curl https://api.1keyplatform.dev/v1/intercoms/1kic-qzrf-rdwy-dvtk/events \
  -H "Authorization: Bearer $ONEKEY_API_KEY"

Needs events:read. An intercom's events are read like a hub's: the same parameters, cursors and retention, with the intercom's ID as hub_id. They are in your organization's log (GET /events) too. The event reference lists them: door.unlocked, door.state, access.denied, call.*, intercom.booted and intercom.power, and the connection and alarm events hubs have.

The event streams signal intercom.created, intercom.updated and intercom.deleted as they do for hubs.

An intercom that was factory reset, or lost its key, can't reconnect with its old certificate. Reset its link and it requests a new certificate on its own, as a hub does:

curl
curl -X POST https://api.1keyplatform.dev/v1/intercoms/1kic-qzrf-rdwy-dvtk/reset-link \
  -H "Authorization: Bearer $ONEKEY_API_KEY"

It stays in your organization, at its site, and enrolled. Owners and admins only. Needs intercoms:write.

Removing an intercom

To start an intercom over completely, or when it leaves for good, remove it:

curl
curl -X DELETE https://api.1keyplatform.dev/v1/intercoms/1kic-qzrf-rdwy-dvtk \
  -H "Authorization: Bearer $ONEKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirm": "1kic-qzrf-rdwy-dvtk"}'

This deletes the intercom's certificates and its AWS IoT thing, and everything recorded about it: events, sessions, uptime, alarms, connection and its enrollment. The building's 1Valet account is not changed. confirm repeats the intercom's ID. The answer is 204, and an intercom.deleted signal goes out on the event streams.

The intercom can't reconnect afterwards. To use it again, factory reset it; once it has requested a new certificate, add it by its Serial. Owners and admins only. Needs intercoms:write.

The desktop intercom's downloads

The desktop virtual intercom keeps itself up to date and fetches its face models on its first run, before it has joined a building, so these two calls take no API key:

curl
curl https://api.1keyplatform.dev/v1/desktop/config
json
{
  "feed_url": "https://api.1keyplatform.dev/v1/desktop/files",
  "models_url": "https://api.1keyplatform.dev/v1/desktop/files/models"
}

feed_url is the folder with the update feed (appcast-macos.xml, appcast-windows.xml) and the packages; models_url the folder with the face models, each under the SHA-256 of its bytes. GET https://api.1keyplatform.dev/v1/desktop/files/{path} redirects (302) to a signed URL for the file, good for an hour. Both are 404 on a 1Key that has no desktop downloads.