# Bridge Overview

A Bridge puts your locks online. Your application sends a job to the iglooworks 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 iglooworks app or the [Mobile SDK](/works/sdk_getting_started).

## How a Job Flows

```mermaid
sequenceDiagram
    participant App as Your Application
    participant API as iglooworks 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

Every Bridge job in the iglooworks API targets a lock through its Bridge: lock, unlock, create or delete a PIN, get battery level, get device status, or get activity logs. Pass `departmentId` unless the account has a single department. See [Lock Jobs](/works/api_jobs#lock-jobs).

## Before You Start

- **Set up the Bridge.** Connect it to the internet in the iglooworks app.
- **Link each lock to a Bridge.** Use the iglooworks app, or the [Mobile SDK](/works/sdk_linking) for in-app linking. The API cannot link locks.
- **Register a webhook URL.** See [Webhook Security](/works/webhook-security#setting-up-your-webhook-url).
- **Request the right scopes.** Each job type has its own scope. See [Available Scopes](/works/individual-account#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 **10 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](/works/bridge-events) and [Job Result Payloads](/works/job-result-payloads).

If a webhook does not arrive, poll [Get Bridge Job Status](/works/api_jobs#get-bridge-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](/works/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 iglooworks 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 Bridge Job Status](/works/api_jobs#get-bridge-job-status) |

## Next Steps

- [Lock Jobs](/works/api_jobs#lock-jobs): send commands to a lock.
- [Bridge Events](/works/bridge-events): handle the webhooks.