Skip to main content

Getting Started

Follow these steps to send your first device command.

Step 1 — Prerequisites​

  • A Fingerspot device connected to the NATS network
  • A cloud_id assigned to your device (found in the device registry)
  • Your API token (V2_API_TOKEN)

Step 2 — Get an Ack​

Send a GET /v2/{cloud_id} to retrieve device info. The response is immediate:

curl -X GET http://localhost:8080/v2/T149000519 \
  -H "X-API-Key: your-secret-token" \
  -H "X-Reference-ID: my-first-command"

Response (200):

{
  "referenceId": "my-first-command",
  "status": "queued",
  "deviceStatus": "connected",
  "message": "command queued successfully",
  "webhookUrls": ["http://your-webhook-url.com/hook"]
}

The referenceId is your identifier — use it to correlate the ack with the webhook callback.

Step 3 — Receive the Webhook​

The result arrives as a POST to your configured webhook URL:

{
  "referenceId": "my-first-command",
  "status": "success",
  "commandType": "getDevice",
  "data": {
    "cloudId": "T149000519",
    "brand": "zkteco",
    "firmwareVersion": "V3.0.2"
  }
}

If your device isn't reachable or the command fails:

{
  "referenceId": "my-first-command",
  "status": "failed",
  "commandType": "getDevice",
  "error": {
    "code": "ERR_INTERNAL",
    "message": "device not found"
  }
}
tip

For security, verify the signature of every webhook you receive. See Signature Verification.

Step 4 — Multiple Webhook URLs​

You can send the callback to additional URLs by passing the X-Webhook-URL header:

curl -X GET http://localhost:8080/v2/T149000519/users \
  -H "X-API-Key: your-secret-token" \
  -H "X-Reference-ID: get-users-1" \
  -H "X-Webhook-URL: https://my-server.com/hook,https://backup-server.com/hook"

The payload is delivered to all URLs concurrently, up to V2_WEBHOOK_MAX_URLS (default 3). The device's registered webhook always receives the payload regardless of this header.

Try It​

Scroll down to the Try It panel on any API page. Fill in the cloud_id, add your X-API-Key in the Auth section, and click Send API Request.

The HTTP response (ack) appears immediately. When the device finishes processing, the webhook callback appears in the Webhook Callback panel below.