SmartBoard Quickstart

This guide shows the shortest path to connect a SmartBoard workflow to the DiamondTracker API v3 with an API key, then run RFID scan and pick-to-light operations.

Base URL:

https://igi.diamondmatch.org

Authenticate

Generate an API key from DiamondTracker and send it on every API request with the x-api-key header. For key creation, expiration, and revocation details, see the API Introduction.

Bash/cURLPythonJavaScript

curl "https://igi.diamondmatch.org/v3/external/users" \
  -H "x-api-key: YOUR_API_KEY"

import requests

response = requests.get(
    "https://igi.diamondmatch.org/v3/external/users",
    headers={"x-api-key": "YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://igi.diamondmatch.org/v3/external/users", {
  headers: { "x-api-key": "YOUR_API_KEY" },
});

if (!response.ok) {
  throw new Error(`API request failed: ${response.status}`);
}

console.log(await response.json());

Note

Keep API keys private. Do not expose them in browser code, public repositories, mobile applications, or customer-visible logs.

RFID Scan Workflow

This workflow is for SmartBoard devices. A SmartBoard scan integration is usually a two-step workflow:

Request a scan from a connected RFID device.
Retrieve the scan result from RFID tracking history by using the returned historyId as the filters[parent_id] value.
The items currently on the SmartBoard are returned in the tagsPresent field.

1. Request A Scan

Call POST /external/devices/action/{serialNumber} with the device serial number and the Scan action.

Bash/cURLPythonJavaScript

curl -X POST "https://igi.diamondmatch.org/v3/external/devices/action/SBRv3-0110" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"Scan"}'

import requests

response = requests.post(
    "https://igi.diamondmatch.org/v3/external/devices/action/SBRv3-0110",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={"action": "Scan"},
    timeout=30,
)
response.raise_for_status()
action = response.json()
print(action["historyId"])

const response = await fetch(
  "https://igi.diamondmatch.org/v3/external/devices/action/SBRv3-0110",
  {
    method: "POST",
    headers: {
      "x-api-key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ action: "Scan" }),
  }
);

if (!response.ok) {
  throw new Error(`Scan request failed: ${response.status}`);
}

const action = await response.json();
console.log(action.historyId);

Successful responses include the tracking identifier to use in the next step:

{
  "message": "Action requested",
  "historyId": "69fb43a9e11e30bb9308e23c"
}

The device must be online and connected to the server when the request is sent. If it is not connected, the API returns a 400 response.

2. Retrieve Scan Results

After requesting the scan, call GET /external/history/rfid-tracking with the parent_id filter set to the historyId returned by the action call.

Bash/cURLPythonJavaScript

curl --globoff "https://igi.diamondmatch.org/v3/external/history/rfid-tracking?filters[parent_id]=69fb43a9e11e30bb9308e23c&size=10" \
  -H "x-api-key: YOUR_API_KEY"

import requests

history_id = "69fb43a9e11e30bb9308e23c"
response = requests.get(
    "https://igi.diamondmatch.org/v3/external/history/rfid-tracking",
    headers={"x-api-key": "YOUR_API_KEY"},
    params={"filters[parent_id]": history_id, "size": 10},
    timeout=30,
)
response.raise_for_status()
print(response.json())

const historyId = "69fb43a9e11e30bb9308e23c";
const url = new URL("https://igi.diamondmatch.org/v3/external/history/rfid-tracking");
url.searchParams.set("filters[parent_id]", historyId);
url.searchParams.set("size", "10");

const response = await fetch(url, {
  headers: { "x-api-key": "YOUR_API_KEY" },
});

if (!response.ok) {
  throw new Error(`History request failed: ${response.status}`);
}

console.log(await response.json());

The response is an array of RFID tracking events. The most important fields are:

Field	Description
`id`	Unique identifier of the resulting RFID tracking event.
`parent_id`	The `historyId` from the scan request.
`serial_number`	Serial number of the RFID device.
`created`	Timestamp of the event.
`tagsAdded`	RFIDs detected as added during the scan.
`tagsRemoved`	RFIDs detected as removed during the scan.
`tagsPresent`	RFIDs present after the scan, These are the tags currently on the smartBoard.

Example response:

[
  {
    "id": "69fb43b7e11e30bb9308e23d",
    "parent_id": "69fb43a9e11e30bb9308e23c",
    "serial_number": "SBRv3-0110",
    "created": "2026-05-06T10:15:30.000Z",
    "tagsAdded": ["3025467532"],
    "tagsRemoved": [],
    "tagsPresent": ["3025467532"]
  }
]

Tip

Scan execution is asynchronous. If the first history request returns an empty array, retry the same request after a short delay.

Pick-To-Light Workflow

This workflow is for SmartBoard devices. Pick-to-light starts from the scan result: use the tagsPresent values returned by GET /v3/external/history/rfid-tracking as the process tags, and set deviceSerialNumbers to the SmartBoard serial number that should light the tags. The deviceSerialNumbers field is an array, even when only one device is used.

1. Create The Process

Create a TAKE process with POST /v3/external/processes.

Bash/cURLPythonJavaScript

curl -X POST "https://igi.diamondmatch.org/v3/external/processes" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Pick-to-light from API quickstart",
    "type": "TAKE",
    "tags": ["3025467532"],
    "deviceSerialNumbers": ["SBRv3-0110"]
  }'

import requests

tags_present = ["3025467532"]
response = requests.post(
    "https://igi.diamondmatch.org/v3/external/processes",
    headers={
        "x-api-key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "description": "Pick-to-light from API quickstart",
        "type": "TAKE",
        "tags": tags_present,
        "deviceSerialNumbers": ["SBRv3-0110"],
    },
    timeout=30,
)
response.raise_for_status()
process = response.json()
print(process["id"])

const tagsPresent = ["3025467532"];
const response = await fetch("https://igi.diamondmatch.org/v3/external/processes", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    description: "Pick-to-light from API quickstart",
    type: "TAKE",
    tags: tagsPresent,
    deviceSerialNumbers: ["SBRv3-0110"],
  }),
});

if (!response.ok) {
  throw new Error(`Process create request failed: ${response.status}`);
}

const process = await response.json();
console.log(process.id);

Successful responses include the process id:

{
  "message": "Item created",
  "id": "69f4b1ee7dcc388e262c47a9"
}

The device must be connected, and each RFID in tags must exist in the inventory.

2. Cancel The Process

Stop the pick-to-light process by calling DELETE /v3/external/processes/{id} with the id returned by the create call.

Bash/cURLPythonJavaScript

curl -X DELETE "https://igi.diamondmatch.org/v3/external/processes/69f4b1ee7dcc388e262c47a9" \
  -H "x-api-key: YOUR_API_KEY"

import requests

process_id = "69f4b1ee7dcc388e262c47a9"
response = requests.delete(
    f"https://igi.diamondmatch.org/v3/external/processes/{process_id}",
    headers={"x-api-key": "YOUR_API_KEY"},
    timeout=30,
)
response.raise_for_status()

const processId = "69f4b1ee7dcc388e262c47a9";
const response = await fetch(`https://igi.diamondmatch.org/v3/external/processes/${processId}`, {
  method: "DELETE",
  headers: { "x-api-key": "YOUR_API_KEY" },
});

if (!response.ok) {
  throw new Error(`Process cancel request failed: ${response.status}`);
}

More API Details

For base URL, authentication, pagination, and inventory customization details, see the API Introduction. The complete OpenAPI documentation is available at API v3 docs.