Skip to main content
POST
/
products
/
api
/
v1
/
products
Create a product
curl --request POST \
  --url https://www.closient.com/products/api/v1/products \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "gtin": "<string>",
  "metadata": {},
  "organization_id": "<string>",
  "product_name": "",
  "description": "",
  "country_of_origin": "",
  "net_content": "",
  "ingredients": "<string>"
}
'
{
  "id": "<string>",
  "gtin": "<string>",
  "product_name": "<string>",
  "is_claimed": true,
  "data_source": "crowd_sourced",
  "confidence_score": 0.5,
  "field_confidence": {},
  "metadata": {},
  "brand": "",
  "manufacturer": "",
  "description": "",
  "image_url": "",
  "country_of_origin": "",
  "net_content": "",
  "net_content_value": 123,
  "net_content_uom": "MLT",
  "owner_id": "<string>",
  "claim_verification_status": "unverified",
  "length": 123,
  "length_uom": "",
  "width": 123,
  "width_uom": "",
  "height": 123,
  "height_uom": "",
  "depth": 123,
  "depth_uom": "",
  "gross_weight": 123,
  "gross_weight_uom": "",
  "net_weight": 123,
  "net_weight_uom": "",
  "gpc_brick_code": "",
  "gpc_class_code": "",
  "gpc_family_code": "",
  "gpc_segment_code": ""
}

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

Body for POST /products — creates a new GTIN and claims it.

gtin is required; all other product fields are optional and may be enriched after creation via PATCH.

​
gtin
string
required

GTIN barcode in any GTIN-8/12/13/14 form. Normalized to GTIN-14 before storage.

Required string length: 8 - 14
​
metadata
Metadata · object

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

​
organization_id
string<shortuuid> | null

URL-safe 22-character shortuuid encoding of the row's UUID primary key. Stable across the row's lifetime; suitable for sharing in URLs, log lines, and external SDK clients. Accepted on input as either the shortuuid form or the canonical UUID form (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
​
product_name
string
default:""

Display name for the new product. Empty string is allowed and may be enriched later via PATCH.

Maximum string length: 255
​
description
string
default:""

Long-form product description. Empty string is allowed.

​
country_of_origin
string
default:""

ISO 3166-1 alpha-2 country code where the product is made. Empty string when unknown.

Maximum string length: 2
​
net_content
string
default:""

Free-text net content as printed on the package (e.g. 340g). Empty string when unknown.

Maximum string length: 100
​
ingredients
string | null

Raw ingredient list text. When provided, the parser splits the text into spans and matches each span to a Substance record. Omit to skip ingredient parsing.

Response

Created

Canonical product record returned by the GTIN repository.

Combines the core trade-item fields, GDSN dimension/weight pairs, GS1 Global Product Classification (GPC) codes, and the Stripe-style metadata map. Crowd-sourced contributions are folded into this shape only after they pass the confidence-promotion threshold.

​
id
string<shortuuid>
required

Internal product identifier (UUID). Stable for the lifetime of the GTIN.

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
​
gtin
string
required

Normalized GTIN-14 (zero-padded). Stable across the catalog regardless of input format.

Required string length: 14
Pattern: ^\d{14}$
​
product_name
string
required

Display name of the product as marketed on the packaging.

​
is_claimed
boolean
required

True when the GTIN has been claimed by a brand owner (i.e. the linked Brand belongs to an Organization).

​
data_source
enum<string>
required

Provenance of the canonical record (e.g. crowd_sourced, open_food_facts, claimed once a brand owner takes ownership).

Available options:
crowd_sourced,
claimed,
imported,
ai_extracted,
brand_site_crawl,
gtin1_authoritative,
external_api,
open_food_facts,
usda_fdc,
fda_ndc,
affiliate_feed,
datakick,
common_crawl_wdc
​
confidence_score
number
required

Aggregate confidence score across all canonical fields, derived from contribution agreement.

Required range: 0 <= x <= 1
​
field_confidence
Field Confidence · object
required

Per-field confidence map, e.g. {"product_name": 0.95, "brand": 0.9}. Each value is in the range 0.0 - 1.0.

​
metadata
Metadata · object

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

​
brand
string
default:""

Brand name resolved from the linked Brand record. Empty string when the GTIN is not yet associated with a brand.

​
manufacturer
string
default:""

Manufacturer name resolved from the linked Manufacturer record. Empty string when no manufacturer is on file.

​
description
string
default:""

Long-form description of the product. May be empty.

​
image_url
string
default:""

Absolute URL of the primary product image. Empty string when the product has no hero image.

​
country_of_origin
string
default:""

ISO 3166-1 alpha-2 country code identifying where the product was made. Empty string when unknown.

Maximum string length: 2
​
net_content
string
default:""

Free-text net content as printed on the package (e.g. 340g, 12 x 330ml). Use net_content_value + net_content_uom for the structured pair.

​
net_content_value
number | null

Structured numeric net content (e.g. 340 for 340g). Null when no structured value has been parsed.

​
net_content_uom
enum<string> | null

UN/CEFACT unit code paired with net_content_value. Null when no structured value has been parsed; expect the empty string on legacy records pending a backfill.

Available options:
MLT,
CLT,
LTR,
GRM,
KGM,
ONZ,
LBR,
PTI,
QTI,
GLL,
EA
​
owner_id
string<shortuuid> | null

URL-safe 22-character shortuuid encoding of the row's UUID primary key. Stable across the row's lifetime; suitable for sharing in URLs, log lines, and external SDK clients. Accepted on input as either the shortuuid form or the canonical UUID form (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx).

Required string length: 22
Pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
​
claim_verification_status
enum<string> | null

Verification tier for the GTIN ownership claim. Null when the GTIN has never been claimed; set automatically to unverified on initial claim and upgraded by external verification signals.

Available options:
unverified,
prefix_matched,
verified,
disputed,
rejected
​
length
number | null

Product length in the unit specified by length_uom. Null when the dimension is unknown.

​
length_uom
string
default:""

UN/CEFACT recommendation 20/21 unit code for the paired dimension (e.g. CMT centimetre, MMT millimetre, MTR metre). Empty string when the dimension is unknown.

Maximum string length: 10
​
width
number | null

Product width in the unit specified by width_uom. Null when the dimension is unknown.

​
width_uom
string
default:""

UN/CEFACT recommendation 20/21 unit code for the paired dimension (e.g. CMT centimetre, MMT millimetre, MTR metre). Empty string when the dimension is unknown.

Maximum string length: 10
​
height
number | null

Product height in the unit specified by height_uom. Null when the dimension is unknown.

​
height_uom
string
default:""

UN/CEFACT recommendation 20/21 unit code for the paired dimension (e.g. CMT centimetre, MMT millimetre, MTR metre). Empty string when the dimension is unknown.

Maximum string length: 10
​
depth
number | null

Product depth in the unit specified by depth_uom. Null when the dimension is unknown.

​
depth_uom
string
default:""

UN/CEFACT recommendation 20/21 unit code for the paired dimension (e.g. CMT centimetre, MMT millimetre, MTR metre). Empty string when the dimension is unknown.

Maximum string length: 10
​
gross_weight
number | null

Gross weight (product + packaging) in the unit specified by gross_weight_uom. Null when unknown.

​
gross_weight_uom
string
default:""

UN/CEFACT recommendation 20/21 unit code for the paired weight (e.g. GRM gram, KGM kilogram, LBR pound, ONZ ounce). Empty string when the weight is unknown.

Maximum string length: 10
​
net_weight
number | null

Net weight (product only, excluding packaging) in the unit specified by net_weight_uom. Null when unknown.

​
net_weight_uom
string
default:""

UN/CEFACT recommendation 20/21 unit code for the paired weight (e.g. GRM gram, KGM kilogram, LBR pound, ONZ ounce). Empty string when the weight is unknown.

Maximum string length: 10
​
gpc_brick_code
string
default:""

GS1 Global Product Classification 8-digit brick code (the most specific level). Empty string when the product has not been classified.

Maximum string length: 8
Pattern: ^(\d{8})?$
​
gpc_class_code
string
default:""

GS1 Global Product Classification class code (parent of brick). Empty string when unclassified.

Maximum string length: 8
Pattern: ^(\d{8})?$
​
gpc_family_code
string
default:""

GS1 Global Product Classification family code (parent of class). Empty string when unclassified.

Maximum string length: 8
Pattern: ^(\d{8})?$
​
gpc_segment_code
string
default:""

GS1 Global Product Classification segment code (top-level category). Empty string when unclassified.

Maximum string length: 8
Pattern: ^(\d{8})?$