Skip to main content
POST
File an adverse report

Authorizations

​
X-API-Key
string
header
required

Body

application/json

Payload to file a new adverse report (consumer-facing).

​
gtin
string
required

GTIN of the product the report is about, from the resolution context.

Pattern: ^[^\x00]{0,}$
​
report_type
enum<string>
required

Typed harm category (illness / injury / allergic_reaction / foreign_object / spoilage / packaging_defect).

Available options:
illness,
injury,
allergic_reaction,
foreign_object,
spoilage,
packaging_defect
​
severity
enum<string> | null

Optional consumer-declared severity (minor / moderate / serious / hospitalization / life_threatening). Omit or null if the consumer declined — Closient never infers it.

Available options:
minor,
moderate,
serious,
hospitalization,
life_threatening
​
body
string
default:""

Freeform description of what happened. May be empty for a voice-only report.

Pattern: ^[^\x00]{0,}$
​
batch
string | null

Batch/lot identifier (GS1 AI 10) from the scan. The lot is the correlation unit for alerts.

Pattern: ^[^\x00]{0,}$
​
voice_session_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}$
​
contact_consent
boolean
default:false

Explicit opt-in to be contacted by the brand about this report.

​
contact_email
string | null

Contact address the consumer agrees to be reached at. Must be one of their own verified account email addresses. Only meaningful when contact_consent is true.

Pattern: ^[^\x00]{0,}$
​
consumer_region
enum<string> | null

Optional state / province / territory the consumer says they are in, as an ISO 3166-2 code (US and Canada only, e.g. US-OR, CA-QC). Coarse by design — never send a precise location. Selects the US or Canadian regulator in the handoff. Omit or null if not declared.

Available options:
US-AL,
US-AK,
US-AZ,
US-AR,
US-CA,
US-CO,
US-CT,
US-DE,
US-DC,
US-FL,
US-GA,
US-HI,
US-ID,
US-IL,
US-IN,
US-IA,
US-KS,
US-KY,
US-LA,
US-ME,
US-MD,
US-MA,
US-MI,
US-MN,
US-MS,
US-MO,
US-MT,
US-NE,
US-NV,
US-NH,
US-NJ,
US-NM,
US-NY,
US-NC,
US-ND,
US-OH,
US-OK,
US-OR,
US-PA,
US-RI,
US-SC,
US-SD,
US-TN,
US-TX,
US-UT,
US-VT,
US-VA,
US-WA,
US-WV,
US-WI,
US-WY,
US-AS,
US-GU,
US-MP,
US-PR,
US-VI,
CA-AB,
CA-BC,
CA-MB,
CA-NB,
CA-NL,
CA-NS,
CA-NT,
CA-NU,
CA-ON,
CA-PE,
CA-QC,
CA-SK,
CA-YT
​
onset_date
string<date> | null

Optional date the harm began (YYYY-MM-DD) as the consumer reports it. Must not be in the future. Omit or null if unknown.

​
onset_time
string<time> | null

Optional local time of day the harm began (HH:MM), as the consumer reports it — no timezone is asserted. Requires onset_date. Omit or null if unknown.

Response

Created

A filed adverse report as the reporter sees it — the receipt.

Carries the immutable reference id, the report's typed fields, the delivery record, and the prefilled regulator handoff (Closient never files on the consumer's behalf — the handoff is how they complete the real report).

​
reference_id
string
required

Immutable, human-facing reference the reporter quotes to track it.

​
id
string<shortuuid>
required

Public short-UUID identifier of the adverse report.

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

GTIN-14 of the product this report is about.

​
report_type
enum<string>
required

Typed harm category code.

Available options:
illness,
injury,
allergic_reaction,
foreign_object,
spoilage,
packaging_defect
​
body
string
required

Freeform description the consumer wrote (may be empty for voice-only).

​
status
string
required

Underlying signal lifecycle code: active or revoked.

​
has_voice
boolean
required

True when a voice capture session backs this report.

​
contact_consent
boolean
required

Whether the consumer opted in to be contacted by the brand.

​
created
string<date-time>
required

ISO-8601 timestamp the report was filed.

​
delivery
DeliveryOut · object
required

The immutable delivery record for this report.

Example:
​
regulator_handoff
RegulatorHandoffOut · object
required

Prefilled handoff to the appropriate regulator — the consumer completes the filing.

Example:
​
batch
string | null

Batch/lot identifier (GS1 AI 10) from the scan, or null.

​
serial
string | null

Serialized-unit context from the scan, or null.

​
severity
enum<string> | null

Consumer-declared severity code, or null if not graded. Never inferred by Closient.

Available options:
minor,
moderate,
serious,
hospitalization,
life_threatening
​
consumer_region
enum<string> | null

Consumer-declared state / province (ISO 3166-2, e.g. US-OR), or null when not declared. Never a precise location, never inferred from IP.

Available options:
US-AL,
US-AK,
US-AZ,
US-AR,
US-CA,
US-CO,
US-CT,
US-DE,
US-DC,
US-FL,
US-GA,
US-HI,
US-ID,
US-IL,
US-IN,
US-IA,
US-KS,
US-KY,
US-LA,
US-ME,
US-MD,
US-MA,
US-MI,
US-MN,
US-MS,
US-MO,
US-MT,
US-NE,
US-NV,
US-NH,
US-NJ,
US-NM,
US-NY,
US-NC,
US-ND,
US-OH,
US-OK,
US-OR,
US-PA,
US-RI,
US-SC,
US-SD,
US-TN,
US-TX,
US-UT,
US-VT,
US-VA,
US-WA,
US-WV,
US-WI,
US-WY,
US-AS,
US-GU,
US-MP,
US-PR,
US-VI,
CA-AB,
CA-BC,
CA-MB,
CA-NB,
CA-NL,
CA-NS,
CA-NT,
CA-NU,
CA-ON,
CA-PE,
CA-QC,
CA-SK,
CA-YT
​
onset_date
string<date> | null

Consumer-declared date the harm began, or null when unknown.

​
onset_time
string<time> | null

Consumer-declared local time of day the harm began (no timezone), or null when unknown.