Docs / igloohome / API Reference / Jobs

Open in Claude Open in ChatGPT llms.txt

Jobs API Reference

API endpoints for managing jobs.

Lock Jobs

Bridge Proxied Jobs send commands to smart locks through a Bridge device. The Bridge acts as an intermediary that communicates with locks via Bluetooth while your application communicates with the Bridge via the API.

Send these jobs with Create a Bridge Proxied Job.

Job Creation

Create a job by making a POST request to:

/devices/{deviceId}/jobs/bridges/{bridgeId}

Request Parameters

Parameter	Type	Description
jobType	number	Command type identifier (see Job Types)
jobData	object	Command-specific parameters

Response

{
  "jobId": "string"
}

Job Types

Job Type	ID
Lock	1
Unlock	2
Create Custom PIN code	4
Delete PIN code	5
Get Battery Level	9
Get Device Status	10
Get Activity Logs	15

Command Details

Lock

Locks the device and optionally synchronizes its internal clock.

Parameter	Type	Description	Required
lockTime	ISO_DATE	Synchronize the lock's clock	No

{
  "jobType": 1,
  "jobData": {
    "lockTime": "2024-01-01T12:00:00+00:00"
  }
}

Unlock

Unlocks the device and optionally synchronizes its internal clock.

Parameter	Type	Description	Required
lockTime	ISO_DATE	Synchronize the lock's clock	No

{
  "jobType": 2,
  "jobData": {
    "lockTime": "2024-01-01T12:00:00+00:00"
  }
}

Create Custom PIN Code

Creates a PIN code with specific access permissions and time restrictions.

Devices/locks supporting PIN are listed in Supported Devices.

Parameter	Type	Description	Required
accessName	string	Display name for the PIN code, up to 60 characters	Yes
pin	string	4-6 digit PIN code	Yes
pinType	number	PIN type (see table below)	Yes
startDate	string	When PIN becomes active (ISO_DATE format)	Yes
endDate	string	When PIN expires (ISO_DATE format)	Duration only

PIN Types

Type	ID	Description
One-Time	1	Valid for 24 hours from start date
Permanent	2	Valid indefinitely from start date
Duration	4	Valid between start and end dates

{
  "jobType": 4,
  "jobData": {
    "accessName": "Guest PIN",
    "pin": "123456",
    "pinType": 4,
    "startDate": "2024-01-01T12:00:00+00:00",
    "endDate": "2024-01-01T16:00:00+00:00"
  }
}

One-Time PIN (24-hour validity):

{
  "jobType": 4,
  "jobData": {
    "accessName": "OTP PIN",
    "pin": "123456",
    "pinType": 1,
    "startDate": "2024-01-01T00:00:00+00:00"
  }
}

Delete PIN Code

Removes a PIN code from the lock. An unactivated AlgoPIN with a start date more than 256 hours after its creation cannot be deleted.

Parameter	Type	Description	Required
pin	string	PIN code to be deleted, 4-9 digits	Yes

{
  "jobType": 5,
  "jobData": {
    "pin": "123456"
  }
}

Get Battery Level

Retrieves the lock's current battery level as a percentage.

{
  "jobType": 9
}

Get Device Status

Queries the lock's current operational status.

{
  "jobType": 10
}

Get Activity Logs

Downloads activity logs from the lock. Optionally synchronizes the lock's clock. Activity logs are deleted from the lock after retrieval.

Parameter	Type	Description	Required
lockTime	ISO_DATE	Synchronize the lock's clock	No

{
  "jobType": 15,
  "jobData": {
    "lockTime": "2024-01-01T12:00:00+00:00"
  }
}

Error Status Codes

Status Code	Description	Applies To
400	Request validation failed, e.g. `job type not supported. see documentation for supported job type(s)` or `pin type not supported. see documentation for supported pin type(s)`	All
401	Missing, invalid or expired access token	All
402	The igloohome API trial has ended, or the billing grace period has expired	All
403	The token lacks the scope for this job type	All
404	Bridge or device not found	All
406	`PIN (123456) is already taken. Please try a different pin`	Create Custom PIN code
406	`Lock is not linked to bridge`	All
406	`Unable to contact bridge as it appears to be offline`	All
415	Missing `Content-Type: application/json`	All
500	Unexpected server error	All

Bridge Jobs

These jobs target the Bridge device itself, not a lock.

Send these jobs with Create a Bridge Targeted Job.

Job Creation

Create a job by making a POST request to:

/devices/{bridgeId}/jobs

bridgeId is the Bridge's device ID.

Parameter	Type
jobType	integer, see Job Types for a full list

{
  "jobType": 10
}

Response

{
  "jobId": "string"
}

Job Types

Job Type	Number
Get Device Status	10

Job Details

Get Device Status (Bridge Diagnostic)

{
  "jobType": 10
}

Once the job completes, you receive a webhook with the result. See Get Device Status for the payload.

Rate limit: one Get Device Status job per bridge every 5 minutes per user. Further requests return 429 with a Retry-After header (seconds).

Error Status Codes

Status Code	Message (API Response)	Description	Applies To
400	Bad Request	The request was unacceptable, often due to a missing or invalid parameter (e.g., `<field>` is required).	All
401	Unauthorized	No valid API key or access token was provided in the request header.	All
402	Payment Required (Various Messages)	The API trial has ended or the payment method was declined. Please verify billing details.	All
403	Forbidden	The authenticated user does not have the necessary permissions (scopes) for this resource.	All
404	Not Found	The requested resource does not exist or the endpoint URL is incorrect.	All
405	Method Not Allowed	The HTTP method used is not supported by this endpoint.	All
406	Unable to contact bridge as it appears to be offline	Unable to contact the bridge. Ensure the physical hardware is powered on and connected.	All
415	Unsupported Media Type	The Content-Type header must be set to application/json.	N/A
429	Too many requests. Please try again after X seconds.	Rate limit exceeded: one job per bridge every 5 minutes per user. Wait for the `Retry-After` seconds.	All
500	Internal Server Error	An unexpected error occurred on our end. Please retry later or contact support.	All

Create a Bridge Targeted Job

POSThttps://api.igloohome.co/home/devices/{bridgeId}/jobs

Creates a job that targets a Bridge device directly, not a lock via a bridge. Supports only jobType 10 (Get Device Status).

Rate limit: one GET_DEVICE_STATUS job per bridge every 5 minutes per user (except for internal igloohome accounts).

Path Parameters

Parameter	Type	Required
bridgeId	string	Yes

Body Parameters

Content-Type:application/json

jobType integer required
10 = Get Device Status. The only supported value.
- Allowed values: 10

Request Example

curl -X POST "https://api.igloohome.co/home/devices/{bridgeId}/jobs" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "jobType": "value"
  }'

const res = await fetch("https://api.igloohome.co/home/devices/{bridgeId}/jobs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "jobType": "value"
  })
});

const data = await res.json();
console.log(data);

import requests

url = "https://api.igloohome.co/home/devices/{bridgeId}/jobs"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Accept": "application/json"
}
payload = {
    "jobType": "value"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.igloohome.co/home/devices/{bridgeId}/jobs"
	payload := []byte(`{
		"jobType": "value"
	}`)

	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Set("Accept", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.igloohome.co/home/devices/{bridgeId}/jobs",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer YOUR_ACCESS_TOKEN",
        "Accept: application/json",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "jobType" => "value"
    ])
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

val client = OkHttpClient()

val mediaType = "application/json".toMediaType()
val body = """
    {
        "jobType": "value"
    }
""".trimIndent().toRequestBody(mediaType)

val request = Request.Builder()
    .url("https://api.igloohome.co/home/devices/{bridgeId}/jobs")
    .method("POST", body)
    .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .addHeader("Accept", "application/json")
    .addHeader("Content-Type", "application/json")
    .build()

val response = client.newCall(request).execute()
println(response.body?.string())

import Foundation

var request = URLRequest(url: URL(string: "https://api.igloohome.co/home/devices/{bridgeId}/jobs")!)
request.httpMethod = "POST"
request.setValue("Bearer YOUR_ACCESS_TOKEN", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Accept")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
let payload: [String: Any] = [
    "jobType": "value"
]
request.httpBody = try? JSONSerialization.data(withJSONObject: payload)

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    if let data = data {
        print(String(data: data, encoding: .utf8) ?? "")
    }
}
task.resume()

Responses

200400401402403404406415429500

Create a Bridge Proxied Job

POSThttps://api.igloohome.co/home/devices/{deviceId}/jobs/bridges/{bridgeId}

Creates a job for a lock via a Bridge device.

Supported Job Types

Job Type	Number
Lock	1
Unlock	2
Create Custom PIN code (duration)	4
Delete PIN code	5
Get Battery Level	9
Get Device Status	10
Get Activity Logs	15

jobData is only required for jobType 4 (Create Custom PIN code) and 5 (Delete PIN code).

jobType	Required jobData fields
4 (Create Custom PIN code)	`accessName`, `pin`, `pinType`, `startDate`, and `endDate` (only when `pinType` is 4/DURATION)
5 (Delete PIN code)	`pin` only

Path Parameters

Parameter	Type	Required
deviceId	string	Yes
bridgeId	string	Yes

Body Parameters

Content-Type:application/json

jobType integer required
See the job type table above
- Allowed values: 1, 2, 4, 5, 9, 10, 15
jobData object
Shape depends on jobType. See the table above. Omit for jobTypes other than 4 and 5.
- accessName string
  Required when jobType is 4 (Create Custom PIN code).
- pinType integer
  1 = One-Time, 2 = Permanent, 4 = Duration. Required when jobType is 4.
  - Allowed values: 1, 2, 4
- pin string
  4-6 digits when jobType is 4 (Create Custom PIN code); 4-9 digits when jobType is 5 (Delete PIN code).
- startDate string<date-time>
  Required when jobType is 4. Must be in format YYYY-MM-DDTHH:mm:ss+hh:mm.
- endDate string<date-time>
  Required when jobType is 4 and pinType is 4 (Duration). Must be in format YYYY-MM-DDTHH:mm:ss+hh:mm and after startDate.

Request Example

curl -X POST "https://api.igloohome.co/home/devices/{deviceId}/jobs/bridges/{bridgeId}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "jobData": "value",
    "jobType": "value"
  }'

const res = await fetch("https://api.igloohome.co/home/devices/{deviceId}/jobs/bridges/{bridgeId}", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "jobData": "value",
    "jobType": "value"
  })
});

const data = await res.json();
console.log(data);

import requests

url = "https://api.igloohome.co/home/devices/{deviceId}/jobs/bridges/{bridgeId}"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Accept": "application/json"
}
payload = {
    "jobData": "value",
    "jobType": "value"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.igloohome.co/home/devices/{deviceId}/jobs/bridges/{bridgeId}"
	payload := []byte(`{
		"jobData": "value",
		"jobType": "value"
	}`)

	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Set("Accept", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.igloohome.co/home/devices/{deviceId}/jobs/bridges/{bridgeId}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer YOUR_ACCESS_TOKEN",
        "Accept: application/json",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "jobData" => "value",
        "jobType" => "value"
    ])
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

val client = OkHttpClient()

val mediaType = "application/json".toMediaType()
val body = """
    {
        "jobData": "value",
        "jobType": "value"
    }
""".trimIndent().toRequestBody(mediaType)

val request = Request.Builder()
    .url("https://api.igloohome.co/home/devices/{deviceId}/jobs/bridges/{bridgeId}")
    .method("POST", body)
    .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .addHeader("Accept", "application/json")
    .addHeader("Content-Type", "application/json")
    .build()

val response = client.newCall(request).execute()
println(response.body?.string())

import Foundation

var request = URLRequest(url: URL(string: "https://api.igloohome.co/home/devices/{deviceId}/jobs/bridges/{bridgeId}")!)
request.httpMethod = "POST"
request.setValue("Bearer YOUR_ACCESS_TOKEN", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Accept")
request.setValue("application/json", forHTTPHeaderField: "Content-Type")
let payload: [String: Any] = [
    "jobData": "value",
    "jobType": "value"
]
request.httpBody = try? JSONSerialization.data(withJSONObject: payload)

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    if let data = data {
        print(String(data: data, encoding: .utf8) ?? "")
    }
}
task.resume()

Responses

200400401402403404406415500

Job Created

Get Job Status

GEThttps://api.igloohome.co/home/jobs/{jobId}

Returns the status of a job you created earlier.

Path Parameters

Parameter	Type	Required
jobId	string	Yes

Request Example

curl -X GET "https://api.igloohome.co/home/jobs/{jobId}" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"

const res = await fetch("https://api.igloohome.co/home/jobs/{jobId}", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Accept": "application/json"
  }
});

const data = await res.json();
console.log(data);

import requests

url = "https://api.igloohome.co/home/jobs/{jobId}"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Accept": "application/json"
}
response = requests.get(url, headers=headers)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.igloohome.co/home/jobs/{jobId}"
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Set("Accept", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.igloohome.co/home/jobs/{jobId}",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer YOUR_ACCESS_TOKEN",
        "Accept: application/json"
    ]
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

val client = OkHttpClient()

val request = Request.Builder()
    .url("https://api.igloohome.co/home/jobs/{jobId}")
    .method("GET", null)
    .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .addHeader("Accept", "application/json")
    .build()

val response = client.newCall(request).execute()
println(response.body?.string())

import Foundation

var request = URLRequest(url: URL(string: "https://api.igloohome.co/home/jobs/{jobId}")!)
request.httpMethod = "GET"
request.setValue("Bearer YOUR_ACCESS_TOKEN", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Accept")

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    if let data = data {
        print(String(data: data, encoding: .utf8) ?? "")
    }
}
task.resume()

Responses

200401402403404422500

{
  "completed": true,
  "expiryDate": "2025-01-01T00:02:00.000Z",
  "jobId": "6345191a82bcfc12a921bdb6",
  "jobResponse": {
    "jobStatus": 0,
    "opResult": {
      "result": 0
    }
  },
  "jobType": "UNLOCK"
}