> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oncanary.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Identifiers and scanning

> Attach, generate, import, and resolve scanner payloads for Canary resources

# 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`.

```bash theme={"theme":"github-light"}
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:

```bash theme={"theme":"github-light"}
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

```json theme={"theme":"github-light"}
{
  "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.