igloo
Get API Key
Docs / igloohome / Bridge / Bridge Overview

Bridge Overview

A Bridge puts your locks online. Your application sends a job to the igloohome API, the API forwards it to the Bridge over the internet, and the Bridge runs it on the lock over Bluetooth. Results come back to you as webhooks.

Without a Bridge, you can only reach a lock from a phone standing next to it, through the igloohome app or the Mobile SDK.

How a Job Flows

sequenceDiagram participant App as Your Application participant API as igloohome API participant Bridge participant Lock rect rgb(255, 245, 243) Note over App,API: 1. Create the job App->>API: POST /devices/{deviceId}/jobs/bridges/{bridgeId} API-->>App: jobId end rect rgb(248, 248, 248) Note over API,Lock: 2. Run the job API->>Bridge: Job over WiFi or Ethernet Bridge->>Lock: Command over Bluetooth Lock-->>Bridge: Result end rect rgb(255, 245, 243) Note over App,Bridge: 3. Get the result Bridge-->>API: Result API-->>App: Job Complete webhook (jobId, jobStatus) end

The POST returns a jobId as soon as the API accepts the job. The lock has not run the command yet. Treat the job as done only when the Job Complete webhook for that jobId arrives.

Lock Jobs and Bridge Jobs

Lock jobs Bridge jobs
Target A lock, through its Bridge The Bridge itself
Endpoint POST /devices/{deviceId}/jobs/bridges/{bridgeId} POST /devices/{bridgeId}/jobs
Examples Lock, unlock, create or delete a PIN, get battery level, get activity logs Get the Bridge's device status
Guide Lock Jobs Bridge Jobs

Before You Start

  • Set up the Bridge. Connect it to the internet in the igloohome app.
  • Link each lock to a Bridge. Use the igloohome app, or the Mobile SDK for in-app linking. The API cannot link locks.
  • Register a webhook URL. See Webhook Security.
  • Request the right scopes. Each job type has its own scope. See Available Scopes.

Supported Bridges

Prefix Bridge Connectivity
EB1X Bridge 2.4 GHz WiFi
EB2X Bridge 2 2.4 GHz WiFi, or Ethernet with the Ethernet adapter accessory

Each Bridge serves up to 5 locks. Bluetooth range depends on the lock model, so test the Bridge position with each lock you install.

Job Lifecycle

Stage What you see
Accepted POST returns 200 with a jobId
Rejected POST returns an error, for example 406 when the Bridge is offline or the lock is not linked
Completed Job Complete webhook with jobStatus 0 (success)
Failed Job Complete webhook with a non-zero jobStatus, for example when the lock is out of range
Timed out No webhook. Poll the job status

Most jobs complete in under a minute. A job with no result after 2 minutes times out. A timed-out job sends no webhook, so poll the job status to see it.

jobStatus Meaning
0 Success
1 Generic error
2 In progress: the Bridge picked up the job and the lock is running it

Getting Results

Use webhooks. The Job Complete webhook carries the result and any data the job returned, such as the battery level. See Bridge Events and Job Result Payloads.

If a webhook does not arrive, poll Get Job Status as a fallback. Poll every 10 seconds, and no more often than every 5 seconds.

Events Without a Job

The Bridge also sends webhooks that no job triggered:

  • Activity Log Received: lock events the Bridge picks up from locks in range, such as unlocks and PIN entries. The Bridge sends them as close to real time as it can, on a best-effort basis.
  • Bridge Connection: the Bridge went online or offline.

See Bridge Events for payloads.

Ordering and Retries

  • Send at most 5 jobs per Bridge in any 2-minute window. Above that, jobs are more likely to fail.
  • The API does not guarantee job order. If order matters, wait for one job's result before you send the next.
  • The API does not retry failed jobs. Create a new job to try again.
  • jobStatus 2 means the job is still running. Before you send it again, wait for the result or the 2-minute timeout, or the lock may run the command twice.

Troubleshooting

Symptom Cause Fix
406 Unable to contact bridge as it appears to be offline Bridge has no power or internet Check power and the network. Watch for the Bridge Connection webhook
406 Lock is not linked to bridge Lock is not linked to this Bridge Link the lock in the igloohome app
Job Complete with jobStatus 1 Lock out of range, or the command failed on the lock Move the Bridge closer to the lock, then send a new job
No webhook after 2 minutes Job timed out, or your webhook URL is missing or unreachable Check your webhook URL, then poll Get Job Status
429 on a Bridge job More than one Get Device Status job per Bridge in 5 minutes Wait for the Retry-After seconds

Next Steps