---
title: "Lookup by barcode"
method: GET
path: "/barcode/{barcode_value}"
tags: ["Barcodes"]
---

# Lookup by barcode

`GET /barcode/{barcode_value}`

## Request

- Base URL: `https://app.colacloud.us/api/v1`
- URL: `https://app.colacloud.us/api/v1/barcode/{barcode_value}`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Find COLAs by barcode value (UPC, EAN, etc.).
Returns up to 100 COLAs associated with the given barcode, subject to remaining quota.
The supplied value is matched exactly first. On a miss, numeric whitespace and
hyphen separators are removed. If still unmatched, a checksum-valid 12-digit
UPC-A may match its zero-prefixed EAN-13, or a zero-prefixed 13-digit EAN may
match its 12-digit UPC-A. Leading-zero recovery requires the corresponding
stored barcode type (ean13 or upca). The first matching value wins; results
from variants are never combined. No fuzzy matching, check-digit repair,
UPC-E expansion, or GTIN-14 conversion is performed. The response barcode_value
echoes the supplied value; barcode_type describes the matched stored barcode.

## Path parameters

- `barcode_value` string, required

## Response `200`

Successful response

- object
  - `data` BarcodeResult
    - `barcode_value` string: The barcode value that was searched
    - `barcode_type` string, nullable: The barcode format (upca, ean13, etc.)
    - `colas` ColaSummary[]: COLAs associated with this barcode
      - `ttb_id` string: Unique TTB identifier
      - `brand_name` string: Brand name on the label
      - `product_name` string: Product name
      - `product_type` 'wine' | 'malt beverage' | 'distilled spirits': Type of alcohol product
      - `class_name` string: TTB classification (e.g., "table red wine")
      - `origin_name` string: Country/region of origin
      - `applicant_trade_name` string, nullable: Applicant DBA/trade name explicitly marked "Used on label" in the captured COLA form, preserving source spelling. Separate from legal company and product brand. Null means no unambiguous marked value was captured, not that the applicant has no trade name.
      - `permit_number` string: Permit number of the producer/importer
      - `application_status` 'approved' | 'expired' | 'surrendered' | 'revoked', nullable: Current application status published by TTB
      - `approval_date` string, date, nullable
      - `image_count` integer: Number of label images
      - `has_barcode` boolean: Whether any barcode was extracted from label images
    - `total_colas` integer: Number of COLAs found

## Other responses

- `401`: Missing or invalid API key or Bearer token
- `404`: Resource not found
- `429`: Quota or burst limit exceeded

---

[API](https://skmtc.dev/colacloud/apis/cola-cloud-api.md) · [All operations](https://skmtc.dev/colacloud/apis/cola-cloud-api/llms.txt) · [OpenAPI document](https://skmtc.dev/colacloud/apis/cola-cloud-api/revisions/1cb00a02112c?raw)