Response customization APIs

Producers can determine the information they provide in their verification responses to the downstream supply chain by configuring custom verification rules. These rules offer Producers significant control over their verification responses to ensure Consumers take appropriate action, including indicating whether an expired product remains safe to sell or whether to return the reason for failed verification.

Set Custom Product Verification Rules (REST)

Producers use this call to configure the information they provide in their verification responses to the downstream supply chain. These custom rules apply to all products for the Producer's company.

Guidelines

Element Type Description
customVerificationRule Object Required. The custom verification rule for the company.
  sendFailureReason Boolean

Required. Indicates whether to return the reason for a failed verification request in the verification response. Valid values:

  • true – (default) The reason for a failed verification request is returned.
  • false – The reason for a failed verification request is not returned.
  sendExpiredStatus Boolean

Required. Indicates whether to return the Expired or Extended Expiration flag in the verification response if the product has expired or the expiration date has been extended. Valid values:

  • true – (default) The Expired flag is returned if product has expired.
  • false – The Expired flag is not returned.

If validWhenExpired equals TRUE, sendExpiredStatus must equal TRUE.
  validWhenExpired Boolean

Required. Indicates whether to return a valid status if the product has expired and is verified as a valid product. Valid values:

  • true – (default) A status of valid is returned if the product has expired and is verified as a valid product.
  • false – A status of invalid is returned.

If validWhenExpired equals TRUE, sendExpiredStatus must equal TRUE.
  sendRecalledStatus Boolean

Required. Indicates whether to return the Recall flag in the verification response if the product has been recalled. Valid values:

  • true – (default) The Recall flag is returned if product has been recalled.
  • false – The Recall flag is not returned.

If validWhenRecalled equals TRUE, sendRecalledStatus must equal TRUE.
  validWhenRecalled Boolean

Required. Indicates whether to return a valid status if the product has been recalled and is verified as a valid product. Valid values:

  • true – (default) A status of valid is returned if the product has been recalled and is verified as a valid product.
  • false – A status of invalid is returned.

If validWhenRecalled equals TRUE, sendRecalledStatus must equal TRUE.
  checkExpirationDay Boolean

Required. Indicates whether the day value in the expiration date is checked in the verification response. Valid values:

  • true – (default) The expiration day is checked.
  • false – The expiration day is not checked.
  sendSuspectStatus Boolean

Required. Indicates whether to return the Suspect flag in the verification response if the product has been marked as suspect. Valid values:

  • true – (default) The Suspect flag is returned if the product has been marked as suspect.
  • false – The Suspect flag is not returned.
  statusesForSuspectProduct Object Required. Indicates whether to return a Suspect flag in the verification response if the serial number being verified is or contains a suspect product and the snStatus and itemStatus values are defined.
    snStatus Enum Array

Required. The serial number status that triggers the return of a suspect product status. Valid values:

  • DECOMMISSIONED
  • DESTROYED

If a value is not specified, this element defaults to null.
    itemStatus Enum

Required. The item status that triggers the return of a suspect product status. Valid value:

  • UNDER_INVESTIGATION

If a value is not specified, this element defaults to null.
  sendIllegitimateStatus Boolean

Required. Indicates whether to return the Illegitimate flag in the verification response if the product has been identified as illegitimate. Valid values:

  • true – (default) The Illegitimate flag is returned if product has illegitimate.
  • false – The Illegitimate flag is not returned.
  statusesForIllegitimateProduct Object Required. An invalid status is returned in addition to the Illegitimate flag if the serial number being verified is or contains an illegitimate product and the snStatus value is defined.

Example

{
   "t":{
      "v":1,
      "m":"pie--producer-set-custom-verification-rules--v1",
      "app-id":"D29A8B05-F8A7-4F35-9C7D-84344E0BE095"
   },
   "p":{
      "customVerificationRule":{
         "checkExpirationDay":true,
         "sendRecalledStatus":true,
         "sendFailureReason":true,
         "sendSuspectStatus":true,
         "validWhenRecalled":true,
         "validWhenExpired":false,
         "sendExpiredStatus":false,
         "statusesForSuspectProduct":{
            "snStatus":[
               
            ],
            "itemStatus":[
               
            ]
         },
         "statusesForIllegitimateProduct":{
            "snStatus":[
               
            ]
         }
      }
   }
}

Guidelines

Element Type Description
customVerificationRule Object Required. The custom verification rule for the company.
  sendFailureReason Boolean

Required. Indicates whether to return the reason for a failed verification request in the verification response. Valid values:

  • true – (default) The reason for a failed verification request is returned.
  • false – The reason for a failed verification request is not returned.
  sendExpiredStatus Boolean

Required. Indicates whether to return the Expired flag in the verification response if the product has expired. Valid values:

  • true – (default) The Expired flag is returned if product has expired.
  • false – The Expired flag is not returned.

If validWhenExpired equals TRUE, sendExpiredStatus must equal TRUE.
  validWhenExpired Boolean

Required. Indicates whether to return a valid status if the product has expired and is verified as a valid product. Valid values:

  • true – (default) A status of valid is returned if the product has expired and is verified as a valid product.
  • false – A status of invalid is returned.

If validWhenExpired equals TRUE, sendExpiredStatus must equal TRUE.
  sendRecalledStatus Boolean

Required. Indicates whether to return the Recall flag in the verification response if the product has been recalled. Valid values:

  • true – (default) The Recall flag is returned if product has been recalled.
  • false – The Recall flag is not returned.

If validWhenRecalled equals TRUE, sendRecalledStatus must equal TRUE.
  validWhenRecalled Boolean

Required. Indicates whether to return a valid status if the product has been recalled and is verified as a valid product. Valid values:

  • true – (default) A status of valid is returned if the product has been recalled and is verified as a valid product.
  • false – A status of invalid is returned.

If validWhenRecalled equals TRUE, sendRecalledStatus must equal TRUE.
  checkExpirationDay Boolean

Required. Indicates whether the day value in the expiration date is checked in the verification response. Valid values:

  • true – (default) The expiration day is checked.
  • false – The expiration day is not checked.
  sendSuspectStatus Boolean

Required. Indicates whether to return the Suspect flag in the verification response if the product has been marked as suspect. Valid values:

  • true – (default) The Suspect flag is returned if the product has been marked as suspect.
  • false – The Suspect flag is not returned.
  statusesForSuspectProduct Object Required. Indicates whether to return a Suspect flag in the verification response if the serial number being verified is or contains a suspect product and the snStatus and itemStatus values are defined.
    snStatus Enum Array

Required. The serial number status that triggers the return of a suspect product status. Valid values:

  • DECOMMISSIONED
  • DESTROYED

If a value is not specified, this element defaults to null.
    itemStatus Enum

Required. The item status that triggers the return of a suspect product status. Valid value:

  • UNDER_INVESTIGATION

If a value is not specified, this element defaults to null.
  sendIllegitimateStatus Boolean

Required. Indicates whether to return the Illegitimate flag in the verification response if the product has been identified as illegitimate. Valid values:

  • true – (default) The Illegitimate flag is returned if product has illegitimate.
  • false – The Illegitimate flag is not returned.
  statusesForIllegitimateProduct Object Required. An invalid status is returned in addition to the Illegitimate flag if the serial number being verified is or contains an illegitimate product and the snStatus value is defined.

Example

{
   "t":{
      "v":1,
      "m":"pie--producer-set-custom-verification-rules-response--v1",
      "app-id":"D29A8B05-F8A7-4F35-9C7D-84344E0BE095",
      "cid":""
   },
   "p":{
      "customVerificationRule":{
         "sendFailureReason":true,
         "sendRecalledStatus":true,
         "checkExpirationDay":true,
         "sendExpiredStatus":false,
         "validWhenExpired":false,
         "validWhenRecalled":true,
         "sendSuspectStatus":true,
         "statusesForSuspectProduct":{
            "snStatus":[
               
            ],
            "itemStatus":[
               
            ]
         },
         "statusesForIllegitimateProduct":{
            "snStatus":[
               
            ]
         }
      }
   }
}

Query Custom Product Verification Rules (REST)

Producers use this call to retrieve and view the information they provide in their verification responses to the downstream supply chain. These custom rules apply to all products for the Producer's company.

Guidelines

Element Type Description
query-control Object Required. The set of controls determining how to return the result set.
  limit Integer

Sets the maximum number of records in the query response.

Example

{
    "t": {
        "v": 1,
        "m": "pie--producer-query-custom-verification-rules--v1",
        "app-id": "267765d3-f913-4c44-85ae-3c25ba7f2b18"
    },
    "p": {
    }
    }

Guidelines

Element Type Description
customVerificationRule Object Required. The custom verification rule for the Producer's company.
  sendFailureReason Boolean

Required. The custom verification rule for the Producer's company.
  sendExpiredStatus Boolean

Required. Indicates whether to return the Expired status in the verification response if the product has expired.

If validWhenExpired equals TRUE, sendExpiredStatus must equal TRUE.
  validWhenExpired Boolean

Required. Indicates whether to return a valid status if the product has expired and is verified as a valid product.

If validWhenExpired equals TRUE, sendExpiredStatus must equal TRUE.
  sendRecalledStatus Boolean

Required. Indicates whether to return the Recall status in the verification response if the product has been recalled.

If validWhenRecalled equals TRUE, sendRecalledStatus must equal TRUE.
  validWhenRecalled Boolean

Required. Indicates whether to return a valid status if the product has been recalled and is verified as a valid product.

If validWhenRecalled equals TRUE, sendRecalledStatus must equal TRUE.
  checkExpirationDay Boolean Required. Indicates whether the day value in the expiration date is checked in the verification response.
  sendSuspectStatus Boolean Required. Indicates whether to return the Suspect status in the verification response if the product has been marked as suspect.
  statusForSuspectProduct Array of Objects Required. Indicates whether to return a suspect product status if the serial number being verified is or contains a suspect product and the snStatus and itemStatus values are defined.
    snStatus Enum

Required. The serial number status that triggers the return of a suspect product status. Valid values:

  • DECOMISSIONED
  • DESTROYED
    itemStatus Enum

Required. The item status that triggers the return of a suspect product status. Valid values:

  • UNDER_INVESTIGATION
  sendIllegitimateStatus Boolean

Required. Indicates whether to return the Illegitimate flag in the verification response if the product has been identified as illegitimate. Valid values:

  • true – (default) The Illegitimate flag is returned if product has illegitimate.
  • false – The Illegitimate flag is not returned.
  statusesForIllegitimateProduct Object Required. An invalid status is returned in addition to the Illegitimate flag if the serial number being verified is or contains an illegitimate product and the snStatus value is defined.
  total-results Integer Required. The total number of results from the query request.
  limit Integer Required. The maximum number of records that can be returned per query.

Example

{
    "t": {
        "v": 1,
        "m": "pie--producer-query-custom-verification-rules-response--v1",
        "app-id": "267765d3-f913-4c44-85ae-3c25ba7f2b18",
        "cid": ""
    },
    "p": {
        "query-metadata-response": {
            "control": {
                "total-results": 1,
                "limit": 100
            }
        },
        "results": {
            "sendFailureReason": true,
            "sendRecalledStatus": true,
            "checkExpirationDay": true,
            "sendExpiredStatus": true,
            "validWhenExpired": true,
            "validWhenRecalled": true,
            "sendSuspectStatus": true,
            "statusesForSuspectProduct": {
                "snStatus": [],
                "itemStatus": []
            },
            "sendIllegitimateStatus": true,
            "statusesForIllegitimateProduct": {
                "snStatus": [
                    "DECOMMISSIONED",
                    "DESTROYED"
                ]
            }
        }
    }
}