Product verification APIs

Consumers verify returned products to ensure that the product is safe to resell according to the Producer. For example, if a Dispenser returned products to a Wholesale Distributor, before that Wholesale Distributor can resell those products, they have to verify that the Pharmaceutical Manufacturer that produced the products still considers the serial numbers valid (i.e. has not marked them as recalled, suspect, destroyed, or invalid in some other way).

Consumers must own Smart Event Manager to verify product.

Set Event (Verify product) (REST)

Consumers use this message to verify serial numbers with a target market in the United States or its territories. Use the eventId returned in the response to retrieve additional information about previous Set Event requests in the Query Event API.

Guidelines

Data Element Occurs
Length		 Type Description
eventTime [1...1]
[1/*]		 String Required. The date and time the Set Event occurred. Specifically, this may indicate when the physical scan is performed or the date and time provided by the calling application.
serialNumberList [1...1]
[1/*]		 String

Required. Indicates the serialized product associated with the Smart Event Manager Event request. The Set Event request API supports the reporting of either one serial number (which is processed synchronously) or multiple serial numbers (which are processed asynchronously).

At minimum, the Smart Event Manager Event request API requires the following:

  • packagingCode
  • serialNumber
  • lotNumber
  • expirationDate
  packagingCode [1...1]
[1/*]		 String

Required. The packaging code of the serialized product. Supports GTIN-14 or NTIN.

This corresponds to the GS1 Application Identifier 01.

  packagingCodeType [0...1]
[0/*]		 String

The type of the serialized product packaging code. The default value is GTIN-14.

See the PackagingCodeType enumeration list for valid values.
  serialNumber [1...1]
[1/*]		 String

Required. The serial number associated with the serialized product. This is specified in the GS1 Application Identifier format without parentheses for the AI keys. AI (01) (21) formatted serial numbers for GTINs. Non-GS1 serial numbers (e.g. China) are expressed in native format.

This corresponds to the GS1 Application Identifier 21.
  lotNumber [1...1]
[1/*]		 String

Required. The lot or batch code associated with the serialized product.

This corresponds to the GS1 Application Identifier 10.
  expirationDate [1...1]
[1/*]		 String Required. Indicates the expiration date of the serialized product in YYMMDD format and corresponds to the GS1 Application Identifier 17 as originally reported in the request message. The element supports the value 00 for the DD element.
  productionDate [0...1]
[0/*]		 Date

The production date associated with the serialized product. This is specified in YYMMDD format.

This corresponds to the GS1 Application Identifier 11.
  variant [0...1]
[0/*]		 String

The internal product variant associated with the serialized product.

This corresponds to the GS1 Application Identifier 20.
  activePotency [0...1]
[0/*]		 String

The active potency associated with the serialized product.

This corresponds to the GS1 Application Identifier 7004.
  barcode [0...1]
[0/*]		 String

The full 2D barcode content of the product scan. At minimum this contains:

  • packagingCode
  • serialNumber
  • lotNumber
  • expirationDate

This field should include the full raw DataMatrix content in the native GS1 Element String, with FNC1 (codeword 232) symbol character separators preserved so the system can parse variable length data elements accurately. For more information, see Section 2.2. GS1 Element Strings of GS1 Data Matrix Guide — Introduction and Implementation Guideline, version 2.2, published May 2015.
  containerID [0...1]
[0/*]		 String The container identifier for the relevant serialNumber.
  containerType [0...1]
[0/*]		 String

Conditionally required if containerID is present. The type of the serialized product containerId. This may be one of the following:

  • GTIN-14
  • SSCC
eventType [1...1]
[1/*]		 String

Required. The nature of the Smart Event Manager event request. As a generic observation API, this Smart Event Manager message captures a variety of supply chain and compliance activities.

Valid value: VERIFYING
locationType [1...1]
[1/*]		 String

Required. The type of the associated locationValue for the serialized product event.

See the LocationType enumeration list for valid values.
locationValue [1...1]
[1/*]		 String Required. The location where the reported supply chain activity takes place.
extensionData [1...1]
[1/*]		 String

Required. Supports a number of name/value pairs for reporting various supply chain and compliance activities.

The extensionData section may contain 0-n name/value pairs. TraceLink reserves these name/value pairs for use in the subsequent synchronous processing for the event. The information in the extensionData section is stored in the Smart Event Manager repository.
  market [1...1]
[1/*]		 String

Required. The market name/value pair indicates the country where the reported event activity occurs. Must be a 2-letter ISO Code of country where event occurs.

See the CountryCode enumeration list for valid values.
  supplyType [0...1]
[0/*]		 String

A name/value pair that indicates a description of the compliance/supply chain activity. Use this to describe shipment activity.

See the SupplyType enumeration list for valid values.
  po [0...1]
[0/*]		 String The Purchase Order associated with the serial numbers in serialNumberList.
  salesOrder [0...1]
[0/*]		 String The Sales Order associated with the serial numbers in serialNumberList.
  return [0...1]
[0/*]		 String The Return Order associated with the serial numbers in serialNumberList.
  transfer [0...1]
[0/*]		 String The Transfer Order associated with the serial numbers in serialNumberList.
  asn [0...1]
[0/*]		 String The Advance Shipped Notice associated with the serial numbers in serialNumberList.
  bol [0...1]
[0/*]		 String The Bill of Lading associated with the serial numbers in serialNumberList.
  packslip [0...1]
[0/*]		 String The Packing Slip associated with the serial numbers in serialNumberList.
  invoice [0...1]
[0/*]		 String The Invoice associated with the serial numbers in serialNumberList.
  destruction [0...1]
[0/*]		 String The Destruction Order associated with the serial numbers in serialNumberList.
  scriptId [0...1]
[0/*]		 String The Script ID associated with the serial numbers in serialNumberList.
  fromBusinessParty [0...1]
[0/*]		 String

Conditionally required if fromBusinessPartyType is present. The identifier of the company where the serialized product ships to. Use with fromBusinessPartyType, which provides the identifier type.

The fromBusinessParty element is typically used with a SHIPPED, UNDO_SHIPPED, RECEIVED, or UNDO_RECEIVED event.
  fromBusinessPartyType [0...1]
[0/*]		 String

Conditionally required if fromBusinessParty is present. A name/value pair that indicates the identifier type of fromBusinessParty.

See the CompanyType enumeration list for valid values.

  toBusinessParty [0...1]
[0/*]		 String

Conditionally required if toBusinessPartyType is present. A name/value pair that indicates the identifier of the company that receives serialized product. Use with toBusinessPartyType, which provides the identifier type.

The toBusinessParty element is typically used with a SHIPPED, UNDO_SHIPPED, RECEIVED, or UNDO_RECEIVED event.
  toBusinessPartyType [0...1]
[0/*]		 String

Conditionally required if toBusinessParty is present. A name/value pair that indicates the identifier type of toBusinessParty.

See the CompanyType enumeration list for valid values.

  userID [0...1]
[0/*]		 String A name/value pair that indicates the email address of the user reporting the event.
customData [0...*]
[0/*]		 String

A number of name/value pairs to support the reporting of various supply chain and compliance activities.

The customData section may contain 0-n name/value pairs. These name/value pairs are user-defined and are not used in the subsequent synchronous or asynchronous processing for the event. The information in the customData section is stored in the Smart Event Manager repository.

  customKey [0...*]
[0/*]		 String Required. The user-defined key to support reporting of unique supply chain and compliance activities.
  customValue [0...*]
[0/*]		 String Required. The user-defined value to support reporting of unique supply chain and compliance activities.
context [1...1] Enum

Required.The reason the product is being verified. Valid values: 

  • dscsaStatusCheck – The product is being verified for routine reasons to retrieve basic verification information, such as the product's expiration date.
  • dscsaExceptionVerification – The product is being verified to retrieve more information about a product.
  • dscsaSuspectIllegitimate – The product is being verified because it is suspected as being illegitimate.
  • dscsaSaleableReturn – The product is being verified to confirm that it can be resold after being returned.
ctrlPossessAtt [1...1]
 Boolean

Required. Indicates whether the company submitting the verification request is in possession of the product they are verifying. Valid values: 

  • True – The company is in possession of the product they are verifying.
  • False – The company is not in possession of the product they are verifying.

Example

{
	"event-header": {
		"v": "1",
		"m": "sem--set-event--v1",
		"lp": "sem--set-event--v1",
		"cid": "ba929463-d9f8-43ce-acbe-31a0965bcaa3",
		"is-err": false,
		"context": {
			"sid": "2263471537323",
			"user-id": "4d145ab2-c697-4c90-ada0-b392c00caa17",
			"user-groups": [],
			"company-id": "ba929463-d9f8-43ce-acbe-31a0965bcaa3"
		}
	},
	"event-payload": {
		"eventTime": "2022-09-21T04:57:23.341Z",
		"serialNumberList": [
			{
				"serialNumber": "100000000000",
			        "lotNumber": "TNN4BKB29Q",
			        "expirationDate": "230918",
			        "packagingCode": "64385625627039"
			}
		],
		"eventType": "VERIFYING",
		"locationType": "SGLN",
		"locationValue": "4385625.40635.0",
		"extensionData": [
			{
				"extensionKey": "market",
			        "extensionValue": "US"
			}
		],
			"customData": [],
			"context": "dscsaSaleableReturn",
			"ctrlPossessAtt": true
		}
	}

Errors

The following errors may be encountered with the Set Event request message:

Error Code Error Messages Description
eventTime The Set Event Request cannot be processed. The eventTime is not specified. The error occurs if the source is empty or null.
The Set Event Request cannot be processed. The eventTime is not properly formatted (e.g. “2018-06-05T01:33:34.711Z”). The error occurs if the source is not in GMT dateTime format.
eventType The Set Event Request cannot be processed. The eventType is not specified. The error occurs if the source is empty or null.
The Set Event Request cannot be processed. The eventType is not valid. The eventType must be one of the following: VERIFYING, SHIPPED, RECEIVED, UNDER_INVESTIGATION, AVAILABLE, DAMAGED, DESTROYED, DISPENSED, STOLEN, SAMPLED_BY_AUTHORITIES, UNDO_SHIPPED, UNDO_RECEIVED, UNDO_UNDER_INVESTIGATION, UNDO_AVAILABLE, UNDO_DAMAGED, UNDO_DESTROYED, UNDO_DISPENSED, UNDO_STOLEN, or UNDO_SAMPLED_BY_AUTHORITIES. The error occurs if the source is present, but there is no matching entry in the lookup file.
expirationDate The Set Event Request cannot be processed. The expirationDate must be in YYMMDD format. The error occurs if the source is not in YYMMDD format.
extensionData The Set Event Request cannot be processed. The extensionData element contains invalid fields. The error occurs if the source contains any fields other than:
  • market
  • supplyType
  • po
  • salesOrder
  • return
  • transfer
  • asn
  • bol
  • packslip
  • invoice
  • destruction
  • scriptId
locationType The Set Event Request cannot be processed. The locationType is not specified. The error occurs if the source is empty or null.
The Set Event Request cannot be processed. The locationType is not valid. The eventType must be one of the following: BR_CNES, BR_CNPJ, BR_CPF, BR_PROF_REG, COMPANYSITEID, DEA, DUNS, DUNS4, GLN, HIN, IN_LOCATION_ID, KR_BUS_REG_NUMBER, KR_PROVIDER_CODE, or SGLN. The error occurs if the source is present, but there is no matching entry in the lookup file.
locationValue The Set Event Request cannot be processed. The locationValue is not specified. The error occurs if the source is empty or null.
market The Set Event Request cannot be processed. The market is not valid. The market value must be a 2 letter ISO Code of country where event occurs. The error occurs if the source is present, but there is no matching entry in the lookup file.
productionDate The Set Event Request cannot be processed. The productionDate must be in YYMMDD format. The error occurs if the source is not in YYMMDD format.
serialNumberList The Set Event Request cannot be processed. The serialNumberList is not specified. The error occurs if the source is empty or null.
The Set Event Request cannot be processed. The serialNumberList must specify a single serial number with serialNumber, lotNumber, expirationDate, and packagingCode fields. The error occurs if the serialNumber, lotNumber, expirationDate, or packagingCode elements are empty or null.
The Set Event Request cannot be processed. The serialNumberList element contains invalid fields. The error occurs if the source contains any fields other than:
  • serialNumber
  • lotNumber
  • expirationDate
  • packagingCode
  • packagingCodeType
  • productionDate
  • variant
  • activePotency
  • barcode
supplyType The Set Event Request cannot be processed. The supplyType is not valid. The eventType must be one of the following: EXPORT, FREE_SAMPLE, CIVIL_PROTECTION, EMERGENCY, DENTAL_PRACTITIONER, EMERGENCY_MEDICAL_PRACTITIONER, SPECIAL_MEDICAL_CARE_FACILITY, MEDICAL_PRACTITIONER, MEDICAL_CARE_FACILITY, MILITARY, OPTICAL_PRACTITIONER, PATIENT, PRISON, UNIVERSITY_RESEARCH_INSTITUTION, SCHOOL or VETERINARY. The error occurs if the source is present, but there is no matching entry in the lookup file.
Main Protocol Element The Set Event Request cannot be processed. The main protocol element contains invalid fields. The error occurs if the main protocol element contains any fields other than:
  • eventTime
  • serialNumberList
  • eventType
  • locationValue
  • locationType
  • extensionData
  • customData
The Set Event Request cannot be processed. The main protocol element fields found outside of the main protocol element. The error occurs if the following elements are found outside of the main protocol element:
  • eventTime
  • serialNumberList
  • locationValue
  • locationType
  • extensionData
  • customData
The Set Event Request cannot be processed. The serialNumberList fields found outside of the serialNumberList. The error occurs if the following elements are included outside of the serialNumberList element:
  • serialNumber
  • lotNumber
  • expirationDate
  • packagingCode
  • packagingCodeType
  • productionDate
  • variant
  • activePotency
The Set Event Request cannot be processed. The extensionData element fields found outside of the extensionData The error occurs if the following elements are included outside of the extensionData element:
  • market
  • supplyType
  • po
  • salesOrder
  • return
  • transfer
  • asn
  • bol
  • packslip
  • invoice
  • destruction
  • scriptId
The Set Event Request cannot be processed. The <duplicate namespace field> is specified more than once. The error occurs if any of the TraceLink namespace fields are specified more than once.

Guidelines

Data Element Occurs
Length		 Type Description
companyID [1...1]
[1/*]		 String The TraceLink-generated company identifier of the user reporting the supply chain activity. In a multi-tenant system, this represents the identifier of the company that owns, can report, and can query the Smart Event Manager request and response data.
userId [1...1]
[1/*]		 String The TraceLink-generated user identifier of the operator user reporting the supply chain activity. This user is authenticated in order to report and query Smart Event Manager request and response data.
eventQueryResponseId [1...1]
[1/*]		 String Required. The TraceLink-generated identifier from the Set Event response providing the search criteria for the Get Result Request.
eventTime [1...1]
[1/*]		 String

Required. The date/time the Set Event occurred. Specifically, this may indicate when the physical scan is performed or the date and time provided by the calling application.

serialNumberList [1...1]
[1/*]		 String

Required. The serialized product associated with the Smart Event Manager event request. The Set Event request API supports the reporting of either one serial number (processed synchronously) or multiple serial numbers (processed asynchronously).

At minimum, the Smart Event Manager Event request API requires the following:

  • packagingCode
  • serialNumber
  • lotNumber
  • expirationDate
  packagingCode [1...1]
[1/*]		 String

Required. The packaging code of the serialized product. Supports GTIN-14 or NTIN.

This may correspond to the GS1 Application Identifier 01.

  packagingCodeType [0...1]
[0/*]		 String

The type of the serialized product packagingCode. The default value is GTIN-14.

See the PackagingCodeType enumeration list for valid values.
  serialNumber [1...1]
[1/*]		 String

Required. The serial number associated with the serialized product. This is specified in the GS1 Application Identifier format without parentheses for the AI keys. AI (01) (21) formatted serial numbers for GTINs. Non-GS1 serial numbers (e.g. China) are expressed in native format.

This corresponds to the GS1 Application Identifier 21.
  lotNumber [1...1]
[1/*]		 String

Required. The lot or batch code associated with the serialized product.

This corresponds to the GS1 Application Identifier 10.
  expirationDate [1...1]
[1/*]		 String Required. Indicates the expiration date of the serialized product in YYMMDD format and corresponds to the GS1 Application Identifier 17 as originally reported in the request message. The element supports the value 00 for the DD element.
  adjustedExpirationDate [1...*]
[1/*]		 String

Required. Provides a normalized expiration date with the day value set to the last day of the month.
  productionDate [0...1]
[0/*]		 Date

The production date associated with the serialized product. This is specified in YYMMDD format.

This corresponds to the GS1 Application Identifier 11.
  variant [0...1]
[0/*]		 String

The internal product variant associated with the serialized product.

This corresponds to the GS1 Application Identifier 20.
  activePotency [0...1]
[0/*]		 String

The active potency associated with the serialized product.

This corresponds to the GS1 Application Identifier 7004.
  barcode [0...1]
[0/*]		 String

The full 2D barcode content of the product scan. At minimum this contains:

  • packagingCode
  • serialNumber
  • lotNumber
  • expirationDate

This field should include the full raw DataMatrix content in the native GS1 Element String, with FNC1 (codeword 232) symbol character separators preserved so the system can parse variable length data elements accurately. For more information, see Section 2.2. GS1 Element Strings of GS1 Data Matrix Guide — Introduction and Implementation Guideline, version 2.2, published May 2015.
  containerID [0...1]
[0/*]		 String The container identifier for the relevant serialNumber.
  containerType [0...1]
[0/*]		 String

Conditionally required if containerID is present. The type of the serialized product containerId. This may be one of the following:

  • GTIN-14
  • SSCC
  eventId [1...*]
[1/*]		 String Required. TraceLink-generated identifier relating to the Smart Event Manager Set Event request. Use this ID in the Query Event message to return all of the information related to the request.
  responseEventId [1...*]
[1/*]		 String Required. TraceLink-generated identifier relating to the Smart Event Manager Set Event response. TraceLink use only.
  status [1...*]
[1/*]		 String

Required. TraceLink-generated status name/value pair indicating the status of the request as determined by a called service.

See the SerialNumberStatus enumeration list for valid values.
  message [1...*]
[1/*]		 String Required. TraceLink-generated message name/value pair indicating additional information associated with the status.
  state [1...*]
[1/*]		 String Required. TraceLink-generated state name/value pair indicating the state of the serial number included in the request.
  respondingCompany [0...1]
[1/*]		 String The GLN identifier of the company that provides the verification response.
eventType [1...1]
[1/*]		 String

Required. The nature of the Smart Event Manager event request. As a generic observation API, the Smart Event Manager message captures a variety of supply chain and compliance activities.

Valid value: VERIFYING

locationType [1...1]
[1/*]		 String

Required. The type of the associated locationValue for the serialized product event.

See the LocationType enumeration list for valid values.
locationValue [1...1]
[1/*]		 String Required. The location where the reported supply chain activity takes place.
extensionData [1...1]
[1/*]		 String

Required. Supports a number of name/value pairs for reporting various supply chain and compliance activities.

The extensionData section may contain 0-n name/value pairs. TraceLink reserves these name/value pairs for use in the subsequent synchronous processing for the event. The extensionData is stored in the Smart Event Manager repository.
  market [1...1]
[1/*]		 String

Required. A name/value pair that indicates the country where the reported event activity occurs. Must be a 2-letter ISO Code of thecountry where event occurs.

See the CountryCode enumeration list for valid values.
  supplyType [0...1]
[0/*]		 String

A name/value pair that indicates a description of the compliance/supply chain activity. Use this to describe shipment activity.

See the SupplyType enumeration list for valid values.
  po [0...1]
[0/*]		 String The Purchase Order associated with the serial numbers in serialNumberList.
  salesOrder [0...1]
[0/*]		 String The Sales Order associated with the serial numbers in serialNumberList.
  return [0...1]
[0/*]		 String The Return Order associated with the serial numbers in serialNumberList.
  transfer [0...1]
[0/*]		 String The Transfer Order associated with the serial numbers in serialNumberList.
  asn [0...1]
[0/*]		 String The Advance Shipped Notice associated with the serial numbers in serialNumberList.
  bol [0...1]
[0/*]		 String The Bill of Lading associated with the serial numbers in serialNumberList.
  packslip [0...1]
[0/*]		 String The Packing Slip associated with the serial numbers in serialNumberList.
  invoice [0...1]
[0/*]		 String The Invoice associated with the serial numbers in serialNumberList.
  destruction [0...1]
[0/*]		 String The Destruction Order associated with the serial numbers in serialNumberList.
  scriptId [0...1]
[0/*]		 String The Script ID associated with the serial numbers in serialNumberList.
  fromBusinessParty [0...1]
[0/*]		 String

Conditionally required if fromBusinessPartyType is present. The identifier of the company where the serialized product ships to. Use with fromBusinessPartyType, which provides the identifier type.

The fromBusinessParty element is typically used with a SHIPPED, UNDO_SHIPPED, RECEIVED, or UNDO_RECEIVED event.
  fromBusinessPartyType [0...1]
[0/*]		 String

Conditionally required if fromBusinessParty is present. A name/value pair that indicates the identifier type of the fromBusinessParty.

See the CompanyType enumeration list for valid values.

  toBusinessParty [0...1]
[0/*]		 String

Conditionally required if toBusinessPartyType is present. A name/value pair that indicates the identifier of the company that receives serialized product. Use with the toBusinessPartyType, which provides the identifier type.

The toBusinessParty element is typically used with a SHIPPED, UNDO_SHIPPED, RECEIVED, or UNDO_RECEIVED event.
  toBusinessPartyType [0...1]
[0/*]		 String

Conditionally required if toBusinessParty is present. A name/value pair that indicates the identifier type of the toBusinessParty.

See the CompanyType enumeration list for valid values.

  userID [0...1]
[0/*]		 String A name/value pair that indicates the email address of the user reporting the event.
  status [0...1]
[0/*]		 String

TraceLink-generated status name/value pair indicating the status of the request as determined by a called service.

See the ExtensionStatus enumeration list for valid values.

customData [0...*]
[0/*]		 String

The customData section supports a number of name/value pairs to support the reporting of various supply chain and compliance activities.

The customData section may contain 0-n name/value pairs. These name/value pairs are user-defined and is not used in the subsequent synchronous or asynchronous processing for the event. The data in the customData section is stored in the Smart Event Manager repository.

  customKey [0...*]
[0/*]		 String Required. The user-defined key to support reporting of unique supply chain and compliance activities.
  customValue [0...*]
[0/*]		 String Required. The user-defined value to support reporting of unique supply chain and compliance activities.
contactPoint [1...1]
[1/*]		 String

Required. The responding company's verification contact information who can be contacted if the company requesting the product verification has questions about that response.

TraceLink automatically includes this information in all response messages.
  email [1...1]
[1/*]		 String Required. The email address of the verification contact.

This information is displayed only in the Response section of the Product Information Exchange's Verify Product screen.

TraceLink automatically includes this information in all response messages.
  telephone [1...1]
[1/*]		 String Required. The phone number of the verification contact.

This information is displayed only in the Response section of the Product Information Exchange's Verify Product screen.

TraceLink automatically includes this information in all response messages.

Example

[
	{
		"event-header": {
			"v": "1",
			"m": "sem--set-event-response--v1",
			"lp": "sem--set-event--v1-5hX7",
			"cid": "ba929463-d9f8-43ce-acbe-31a0965bcaa3",
			"is-err": false,
			"context": {
				"from-ms": "ms-tl-app-sem",
				"time": 1666259837612,
				"eid": "9faf906b-932e-49b7-9e62-f118e00b9cc9",
				"sid": "2263471537323",
				"spid": "tracelink-semapp",
				"user-id": "4d145ab2-c697-4c90-ada0-b392c00caa17",
				"user-groups": [],
				"company-id": "ba929463-d9f8-43ce-acbe-31a0965bcaa3"
			}
		},
		"event-payload": {
			"eventQueryResponseId": "bff2f810-ec2b-40ec-8959-a2b8927b0a41",
			"eventTime": "2022-09-21T04:57:23.341Z",
			"serialNumberList": [
				{
					"eventId": "379e5981-5834-4721-9612-3f1e9c6f9b66",
					"responseEventId": "3bc5d9d9-9396-48d0-a50b-55097648a310",
					"serialNumber": "100000000000",
					"lotNumber": "TNN4BKB29Q",
					"expirationDate": "230918",
					"adjustedExpirationDate": "230918",
					"packagingCode": "64385625627039",
					"status": "PIE_SUCCESS",
					"message": "The product was verified by the manufacturer"
				}
			],
			"eventType": "VERIFYING",
			"locationType": "SGLN",
			"locationValue": "4385625.40635.0",
			"extensionData": [
				{
					"extensionKey": "market",
					"extensionValue": "US"
				},
				{
					"extensionKey": "status",
					"extensionValue": "SUCCESS"
				},
				{
					"extensionKey": "message",
					"extensionValue": ""
				}
			],
			"customData": [],
			"contactPoint": {
				"email": "DemoProducerResponder@gmail.com",
				"telephone": "893427987498"
			}
		}
	}
]

Errors

See HTTP response status codes for standard error status codes.

Query Event (Verify product) (REST)

Consumers use this message to retrieve the request and response data related to multiple Set Event requests. This API supports where-like arguments to retrieve the desired set of data. The result of the Query Event returns the full set of data as captured in the Set Event requests and responses.

Guidelines

Data Element Occurs
Length		 Type Description
time [0...1]
[1/*]		 String Use this to query using time parameters.
  past [0...1]
[1/*]		 String Returns all events based upon a number and unit (e.g. minutes, hours, days). *1
    amount [0...1]
[1/*]		 String Required. The amount of time.  *2
    unit [0...1]
[1/*]		 String

Required. The unit of time relating to the amount. Valid values: *3

  • MILLIS
  • SECONDS
  • MINUTES
  • HOURS
  • DAYS
  • WEEKS
  timestamp [0...1]
[1/*]		 String Returns all events based upon a start and end time. *4
    start [0...1]
[1/*]		 String Required. The start time in UTC Event Date Time format. *5
    end [0...1]
[1/*]		 String Required. The end time in UTC Event Date Time format. *6
  date-time [0...1]
[1/*]		 String Returns all events based upon a start and end date. *7
    start [0...1]
[1/*]		 String Required. The start date (e.g. 200307).
    end [0...1]
[1/*]		 String Required. The end date (e.g. 200308).
  since [0...1]
[1/*]		 String Returns all events since the specified timestamp or date. *8
    mode [0...1]
[1/*]		 String

Required. The type of since query. Valid values:

  • date-time
  • timestamp
    timestamp [0...1]
[1/*]		 String Conditionally required if mode equals timestamp. The time in UTC Event Date Time format.
    date-time [0...1]
[1/*]		 String Conditionally required if mode equals timestamp. The date (e.g. 200307).
select [0...1]
[1/*]		 String The set of fields to return in the Query Event response. *9
  fields [0...1]
[1/*]		 String Required. Grouping for desired fields.
    name [0...1]
[1/*]		 String Required. Valid value: data
    expression [0...1]
[1/*]		 String Required. A list of desired fields to retrieve. This may include any fields that were included in the Set Event request.
query-filter [0...1]
[1/*]		 String The name/value pairs to be used as search criteria for the Query Event request. The select search criteria may include any fields that were included in the Set Event request. *10

Query Options

The following are example components of a Query Event with parameters for each query option:

If including an expiration date in a Query Event, and if an adjustedExpirationDate value is returned in the response messages, use the adjustedExpirationDate value, not the expirationDate value in the query.

The eventTime represents the only timestamp field in the Smart Event Manager. The Query Event may use the eventTime search criteria in any of the following ways:

Past - Returns all events based upon a number and unit (e.g. minutes, hours, days, weeks):

"past": {
	"amount": "2",
	"unit": "MINUTES"
}

Timestamp Range - Returns all events based upon a start and end time:

"timestamp": {
	"start": "1523229645000",
	"end": "1523229646000"
}

Date-Time Range - Returns all events based upon a start and end date:

"date-time": {
	"start": "2018-04-08T23:28:50Z",
	"end": "2018-04-08T23:30:50Z"
}

Since Timestamp - Returns all events since the specified timestamp:

"since": {
	"timestamp": "1523229646000",
	"mode": "TIMESTAMP"
}

Since Date-Time - Returns all events since the specified date time:

"since": {
	"date-time": "2018-04-08T23:30:50Z",
	"mode": "DATETIME"
}

The select field provides the set of fields to be returned in the Query Response. The select fields may include any fields in the TraceLink namespace that were included in a Set Event Request.

Example: 

"select": {
	"fields": [
	{
	"name": "data",
	"expression": "$.['eventId', 'eventTime', 'eventType', 'market',
	'serialNumber', 'lotNumber', 'expirationDate',
	'packagingCode', 'packagingCodeType',
	'status','message','state']"
	}
    ]
}

The query filter provides name/value pairs to be used as search criteria for the Query Event Request. The select search criteria may include any fields in the TraceLink namespace that were included in a Set Event Request.

Example: 

"query-filter": {
	"serialNumber": "01089060842103092110000000349317180131"
}

Example

{
    “t”: {
        “v”: 1,
        “m”: “sem—query-events—v1”,
        “app-id”: “D29A8B05-F8A7-4F35-9C7D-84344E0BE095”
        },
        “p”: {
            “query-metadata”: {
            “control”: {
            },
            “select”: {
                “fields”: [
                    {
                        “name”: “data”,
                        “expression”: “$.[‘eventType’, ‘serialNumber’, ‘lotNumber’, ‘packagingCode’, ‘state’, ‘status’]”
                    }
                ]
            }
        },
        “query-filter”: {
            “serialNumber”: "PK009FF8895F416984B”
        }
    }
}

Guidelines

Data Element Occurs
Length		 Type Description
time [0...1]
[1/*]		 String Use this to query using time parameters.
  past [0...1]
[1/*]		 String Returns all events based upon a number and unit (e.g. minutes, hours, days). *11
    amount [0...1]
[1/*]		 String Required. The amount of time.  *12
    unit [0...1]
[1/*]		 String

Required. The unit of time relating to the amount. Valid values: *13

  • MILLIS
  • SECONDS
  • MINUTES
  • HOURS
  • DAYS
  • WEEKS
  timestamp [0...1]
[1/*]		 String Returns all events based upon a start and end time. *14
    start [0...1]
[1/*]		 String Required. The start time in UTC Event Date Time format. *15
    end [0...1]
[1/*]		 String Required. The end time in UTC Event Date Time format. *16
  date-time [0...1]
[1/*]		 String Returns all events based upon a start and end date. *17
    start [0...1]
[1/*]		 String Required. The start date (e.g. 200307).
    end [0...1]
[1/*]		 String Required. The end date (e.g. 200308).
  since [0...1]
[1/*]		 String Returns all events since the specified timestamp or date. *18
    mode [0...1]
[1/*]		 String

Required. The type of since query. Valid values:

  • date-time
  • timestamp
    timestamp [0...1]
[1/*]		 String Conditionally required if mode equals timestamp. The time in UTC Event Date Time format.
    date-time [0...1]
[1/*]		 String Conditionally required if mode equals timestamp. The date (e.g. 200307).
select [0...1]
[1/*]		 String The set of fields to return in the Query Event response. *19
  fields [0...1]
[1/*]		 String Required. Grouping for desired fields.
    name [0...1]
[1/*]		 String Required. Valid value: data
    expression [0...1]
[1/*]		 String Required. A list of desired fields to retrieve. This may include any fields that were included in the Set Event request.
query-filter [0...1]
[1/*]		 String The name/value pairs to be used as search criteria for the Query Event request. The select search criteria may include any fields that were included in the Set Event request. *20

Example

{
    “t”: {
        “v”: 1,
        “m”: “sem—query-events-response—v1”,
        “app-id”: “D29A8B05-F8A7-4F35-9C7D-84344E0BE095”,
        “cid”: “”
    },
    “p”: {
        “query-metadata-response”: {
            “control”: {
            “total-results”: 10,
            “skip”: 0,
            “limit”: 0
            }
        },
        “results”: [
            {
                “data”: {
                “eventType”: “VERIFYING”,
                “serialNumber”: “PK009FF8895F416984B”,
                “lotNumber”: “TEST2C9588146D”,
                “packagingCode”: “86740665964858”,
                “status”: “PIE_SUCCESS”
            },
            “id”: “47f0b051-d01c-49de-b214-d8f8592189bc”
            }
        ]
    }
}

Errors

See HTTP response status codes for standard error status codes.