Identifiers and scanning

Identifiers map exact barcode or QR payloads to assets, locations, and parts inside an organization. Customer part barcodes may be shared by multiple parts; asset, location, and Canary-generated labels remain unique. The public API supports customer-owned labels and Canary-generated QR values.

Choose a workflow

Goal	Operation
Attach an existing label	`POST /identifiers`
Generate a Canary label value	`POST /identifiers/generate`
Resolve scanner output	`POST /identifiers/resolve`
Validate a migration batch	`POST /identifiers/import/preview`
Apply a validated batch	`POST /identifiers/import/apply`
List labels for one record	`GET /identifiers?target_type=...&target_id=...`
Retire a mapping	`DELETE /identifiers/{id}`

Attach an existing label

Send the identifier’s business system and value with its Canary target. payload defaults to value.

curl --fail-with-body --request POST \
  "https://api.oncanary.com/v1/identifiers" \
  --header "Authorization: Bearer $CANARY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "target": {
      "type": "asset",
      "id": "01JAY7C1NQZ5H2R8M4K6T9V3BP"
    },
    "system": "erp-asset-tag",
    "value": "COMPRESSOR-1042",
    "is_primary": true
  }'

An identifier can carry up to 32 scan_values when one physical label has several exact scanner representations. Preserve each raw payload, including a GS1 group separator when present.

Resolve scanner output

Send the scanner’s raw output unchanged:

curl --fail-with-body --request POST \
  "https://api.oncanary.com/v1/identifiers/resolve" \
  --header "Authorization: Bearer $CANARY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "payload": "COMPRESSOR-1042",
    "symbology": "qr_code"
  }'

alternate_payloads accepts up to three additional exact values when a scanner library emits multiple candidates. The resolver is organization-scoped and omits archived records and unavailable modules. The response data.status is resolved for one target, unclaimed for no admitted match, or ambiguous when multiple parts share a customer barcode. An ambiguous result includes up to 20 candidates, each with target, name, partNumber, and identifier metadata. Require the user to choose a candidate; never automatically use the first. hasMore: true means additional matches exist and the user should search the parts catalog.

Generate a Canary identifier

{
  "target": {
    "type": "location",
    "id": "01JAZ04QW7S3R9N6K2V5M8H1CT"
  },
  "is_primary": true
}

Send that body to POST /identifiers/generate. Store and render the returned scan value exactly.

Import in two phases

For bulk migrations, send up to 1,000 rows to /identifiers/import/preview. Resolve every reported validation or conflict before sending the same row shape to /identifiers/import/apply. The apply operation is atomic: any conflict prevents the batch from being committed. A 409 identifier_conflict can indicate a duplicate payload or a conflicting primary assignment.

Payload rules

Payload identity is exact and case-sensitive.
value and payload accept up to 4,096 UTF-8 bytes.
system accepts up to 255 bytes.
format_hint accepts up to 64 bytes.
Resolve within the organization associated with the API key.
Retiring an identifier removes its active scan values from resolution.

API essentials

Work management

Equipment

Inventory

Organization data

Identifiers and scanning

Identifiers and scanning

Choose a workflow

Attach an existing label

Resolve scanner output

Generate a Canary identifier

Import in two phases

Payload rules

​Identifiers and scanning

​Choose a workflow

​Attach an existing label

​Resolve scanner output

​Generate a Canary identifier

​Import in two phases

​Payload rules

Identifiers and scanning

Choose a workflow

Attach an existing label

Resolve scanner output

Generate a Canary identifier

Import in two phases

Payload rules