Skip to main content
POST
/
scanner
/
api
/
v1
/
captures
Submit a barcode or QR scan
curl --request POST \
  --url https://www.closient.com/scanner/api/v1/captures \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "session_short_id": "<string>",
  "capture_type": "BARCODE",
  "raw_value": "<string>",
  "metadata": {},
  "gtin": "",
  "gs1_dl_data": {}
}
'
{
  "status": "PENDING",
  "capture_type": "BARCODE",
  "raw_value": "<string>",
  "gtin": "<string>",
  "error_message": "<string>",
  "created": "2023-11-07T05:31:56Z",
  "metadata": {},
  "gs1_dl_data": {},
  "product_short_id": "<string>",
  "product_name": "<string>",
  "processed_at": "2023-11-07T05:31:56Z",
  "uploaded_image_key": "<string>",
  "qr_analysis": {}
}

Documentation Index

Fetch the complete documentation index at: https://docs.closient.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
X-API-Key
string
header
required

Body

application/json

Request body for submitting a barcode or QR code scan.

​
session_short_id
string
required

Short ID of the active scan session.

​
capture_type
enum<string>
required

How the capture was produced. BARCODE for client-side barcode/QR detection, IMAGE for a server-side image to be analyzed by the vision pipeline, MANUAL for an operator-typed identifier.

Available options:
BARCODE,
IMAGE,
MANUAL
​
raw_value
string
required

Raw barcode or QR code value.

Required string length: 1 - 500
​
metadata
Metadata · object

Developer-attached key/value data. Send {} or null to clear. Empty-string values delete that key. Omitted keys are preserved.

​
gtin
string
default:""

Normalized GTIN-14, if applicable.

Maximum string length: 14
​
gs1_dl_data
Gs1 Dl Data · object

Application Identifiers from a GS1 Digital Link QR code.

Response

201 - application/json

Created

Scan capture with processing status and matched product data.

​
status
enum<string>
required

Processing status of this capture. Captures progress PENDING → LOOKING_UP → ENRICHING → RESOLVING → COMPLETED; FAILED is set on any unrecoverable error (see error_message) and NOT_FOUND is set when the GTIN does not match a known product after lookup.

Available options:
PENDING,
LOOKING_UP,
ENRICHING,
RESOLVING,
COMPLETED,
FAILED,
NOT_FOUND
​
capture_type
enum<string>
required

How the capture was produced. BARCODE for client-side detection, IMAGE for an uploaded image awaiting vision extraction, MANUAL for an operator-typed identifier.

Available options:
BARCODE,
IMAGE,
MANUAL
​
raw_value
string
required

Raw value as detected.

​
gtin
string
required

Normalized GTIN-14.

​
error_message
string
required

Error message if processing failed.

​
created
string<date-time>
required

Timestamp when the capture was created.

​
metadata
Metadata · object

Developer-attached key/value data attached to this object. Up to 50 keys; key max 40 chars, value max 500 chars.

​
gs1_dl_data
Gs1 Dl Data · object

Application Identifiers from GS1 DL.

​
product_short_id
string | null

Slug of the matched product.

​
product_name
string | null

Name of the matched product.

​
processed_at
string<date-time> | null

Timestamp when processing completed.

​
uploaded_image_key
string | null

Storage key of the uploaded image file.

​
qr_analysis
Qr Analysis · object

QR-redirect-chain analysis result populated by the background pipeline when raw_value is an HTTP(S) URL. Keys: initial_url, final_url, hops (list of {url, status_code, headers}), hop_count, resolver_domain, resolver_type (CLOSIENT / GS1_DL / URL_SHORTENER / DIRECT / UNKNOWN), is_closient_resolver, extracted_gtin, error_message. None until the analyzer task has run or when the capture has no URL to analyze.