Verification history APIs

Producers can view the details of previous product verifications performed against their serial number information, both by members of the downstream supply chain and the Producer's own company (for internal verification). These verification history reports can be generated based on either a date range or verification status.

Submit Verification History Request (REST)

Producers use this message to request a report containing previous product verifications performed in Product Information Manager. Use the requestId that is returned in the response to check the status of the verification history request in the Poll Verification History Request Processing API.

Guidelines

Element Type Description
startDateRange String Required. The beginning of the date range for which to download the verification history. The startDateRange time is always midnight GMT of the selected date.
The maximum time range for a verification history request is 7 days. If a date range greater than 7 days is present, Product Information Manager defaults to 7 days.
endDateRange String Required. The end of the date range for which to download the verification history.

The maximum time range for a verification history request is 7 days. If a date range greater than 7 days is present, Product Information Manager defaults to 7 days.

verificationStatus String The verification status of the verification history. Valid values:
  • VALID – Returns only records where verificationResponseResult = VALID.
  • INVALID – Returns only records where verificationResponseResult = INVALID.

If this element is not present, the response includes all verification history records with a verificationResponseResult of VALID or INVALID.

Example

{
    "t": {
        "v": 1,
        "m": "pie--submit-verification-history-request--v1",
        "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C"
    },
    "p": {
        "startDateRange": "25-01-2019",
        "endDateRange": "27-01-2019"
    }
}

Guidelines

Element Type Description
requestId String Required.The unique identifier that is used in the Poll Verification History Request Processing API to check the status of a Submit Verification History Request.

Example

{
    "t": {
        "v": 1,
        "m": "pie--submit-verification-history-request-response--v1",
        "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C"
    },
    "p": {
        "requestId": "8f996821-fd3f-402a-b3cd-8c5cd32f4e1d"
    }
}

Query Verification History Requests (REST)

Producers use this message to query for verification history requests submitted by their company through the Submit Verification History Request API. Use the fileId returned in the response to download the CSV file containing the verification history report in the Download Verification History Report API.

Guidelines

If the query does not include both a date range and request status, the response message includes all request IDs generated in the previous 7 days.

Element Type Description
query-metadata Object The array containing the maximum limit of records returned and possible fields.
  control Object Required. The information about the number of records that can be returned per query.
    limit Integer Sets the maximum number of records that can be returned per query.
    query-token String A token available in the query response. The query token can be used in a new request to return the next set of results when more than one page of results are available.
  time Object Filters events by date and time.
    field-name Enum

Required. Name of the field in the verification history request record to retrieve. Valid values:

  • createdDateTime – The query returns verification history requests based on the date and time the request is created.
  • generatedDateTime – The query returns verification history requests based on the date and time the request is complete.
    mode Enum Required. Indicates how to use the date and time to filter verification history requests. Valid value: PAST.

If a value is not specified, this element defaults to PAST.
    past Object Filters past requests.
      amount Integer Required. Amount of time units.
      unit Enum Required. Unit of time by which to filter the results. Valid values:
  • DAYS
  • HOURS
  • MINUTES
  • MILLIS
  • SECONDS
query-filter Object Query filter for verification history requests. If query-filter is not present, the message queries all verification history requests in the previous 7 day.
  requestStatus Enum The processing status of the verification history request submission. If the request status is not present, the response returns all request IDs in the query date range. Valid values:
  • COMPLETE – The file containing verification history records is ready for download.
  • ERROR – An error occurred during processing.
  • PENDING – The asynchronous processing of the verification history request has not started.
  • PROCESSING – Product Information Manager is generating the file containing the requested verification history.

Example

{
    "t": {
        "v": 1,
        "m": "pie--query-verification-history-requests--v1",
        "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C",
        "cid": "a3c2890e-12a8-4b37-8c8b-6aa47032a18a"
    },
    "p": {
        "query-metadata": {
            "control": {
                "limit": 100,
                "query-token": "drt433"
            }
        },
  	    "time": {
            "field-name": "createdDateTime",
            "mode": "PAST",
            "past": {
                "amount": "5",
                "unit": "MINUTES"
            }
        }
        "query-filter": {
            "requestStatus": "COMPLETE"		
        }
    }
}

Guidelines

Element Type Description
query-metadata-response Array Required. A list containing the maximum limit of records returned and possible fields.
  control String The information about the number of records that can be returned per query.
    total-results Integer The total number of results from the query request.
    limit Integer Indicates the maximum number of records that can be returned per query.
    query-token String A token available in the query response. The query token can be used in a new request to return the next set of results when more than one page of results are available.
requests Array Required. A list of requests and corresponding details of verification history request submissions. The initial query determines the results in this response.
  requestId String The request ID corresponding to the Submit Verification History Request.
  requestStatus String The processing status of the verification history request submission. Valid values:
  • COMPLETE – The file containing verification history records is ready for download.
  • ERROR – An error occurred during processing.
  • PENDING – The asynchronous processing of the verification history request is pending.
  • PROCESSING – Product Information Exchange is generating the file containing the requested verification history.
  reportInfo Object Details regarding the Verification History report.
    generatedDateTime String The date and time the request is completed and the report generated.
    createdDateTime String The date and time the request is created.
    createdBy String The name of the user initiating the request.
    startDateRange String The date range start in the original verification history request.
    endDateRange String The date range end in the original verification history request.
    verificationStatus Enum The status of the verification response in the original verification history request. Valid values:
  • INVALID – Returns only records where verificationResponseResult = INVALID.
  • VALID – Returns only records where verificationResponseResult = VALID.
    files Object The files corresponding to a specific verification history request.
      fileName String The name of the file.
      fileId String The ID of the CSV file containing the Verification History report. Use this ID to download the file in the Download Verification History Report API.
    failureReason String The reason for a verification request failure. The failure reason is present if requestStatus = ERROR.

Example

{
    "t": {
        "v": 1,
        "m": "pie--query-verification-history-requests-response--v1",
        "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C",
        "cid": "a3c2890e-12a8-4b37-8c8b-6aa47032a18a"
    },
    "p": {
        "query-metadata-response": {
            "control": {
                "total-results": 1,
                "limit": 100,
                "query-token": "drt433"
            }
        },
  	    "requests": [
            {
                "requestId": "8f996821-fd3f-402a-b3cd-8c5cd32f4e1d",
                "reportInfo": {
                    "generatedDateTime": "2019-01-27:13:04:21.012Z",
                    "createdDateTime": "2019-01-27:13:04:21.012Z",
                    "startDateRange": "27-01-2019",
                    "endDateRange": "27-01-2019"
                },
                "files": [
                    { "fileId": "8f996821-fd3f-402a-b3cd-8c5cd32f4e1d" }
                ]    	
            }
        ]
    }
}

Poll Verification History Request Processing (REST)

Producers use this message to check the status of the asynchronously processed Submit Verification History Request API request using the requestId returned in the initial Submit Verification History Request response. When processing is complete, use the fileId returned in this response to download the CSV file containing the verification history report in the Download Verification History Report API.

Guidelines

Element Type Description
requestId String Required. The unique identifier a user receives from TraceLink to check the status of a verification history download request. This ID is returned in the Submit Verification History Request response.

Example

{
    "t": {
        "v": 1,
        "m": "pie--poll-verification-history-request--v1",
        "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C"
    },
    "p": {
        "requestId": "8f996821-fd3f-402a-b3cd-8c5cd32f4e1d"
    }
}

Guidelines

Element Type Description
requestId String Required. The request ID sent in the Poll Verification History Request Processing request.
requestStatus Enum Required. The processing status of the verification history request submission. Valid values:
  • COMPLETE – The file containing verification history records is ready for download.
  • ERROR – An error occurred during processing.
  • PENDING – The asynchronous processing of the verification history request is pending.
  • PROCESSING – Product Information Exchange is generating the file containing the requested verification history.
requestResult Object Required. The result of the request. This field will be only contain values if requestStatus = COMPLETE.
  reportInfo Object Details regarding the Verification History report request.
    generatedDateTime String The date and time the request is completed and the report generated.
    createdDateTime String The date and time the request is created.
    createdBy String The name of the user initiating the request.
    startDateRange String The start of the date range in the original verification history request.
    endDateRange String The end of the date range in the original verification history request.
    verificationStatus Enum The status of the verification response in the original verification history request. Valid values:
  • INVALID – Returns only records where verificationResponseResult = INVALID.
  • VALID – Returns only records where verificationResponseResult = VALID.
    files Array A list of files corresponding to verification history requests.
      fileName String The name of the file.
      fileId String The ID of the CSV file containing the Verification History report. Use this ID to download the file in the Download Verification History Report API.
    failureReason String The reason for a verification request failure. The failure reason is present if requestStatus = ERROR.

Example

{
    "t": {
        "v": 1,
        "m": "pie--poll-verification-history-request-response--v1",
        "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C",
        "cid": "ed84ffd9-b0fd-414a-b76e-d683f014ccd9"
    },
    "p": {
        "requestId": "8f996821-fd3f-402a-b3cd-8c5cd32f4e1d",
        "requestStatus": "COMPLETE",
        "requestResult": {
            "reportInfo": {
                "generatedDateTime": "2019-01-27:13:04:21.012Z",
                "createdDateTime": "2019-01-27:13:04:21.012Z",
                "startDateRange": "27-01-2019",
                "endDateRange": "27-01-2019",
                "verificationStatus": "VALID",
                "files": [
                    { "fileName": "my_verification_history_report.csv",
                      "fileId": "8f996821-fd3f-402a-b3cd-8c5cd32f4e1d"
                    }
                ]
            }
        }    
    }
}

Download Verification History Report (REST)

Producers use this message to download the CSV file containing a verification history report requested using Submit Verification History Request API. Use the fileId returned in either the Poll Verification History Request Processing response or Query Verification History Request response to retrieve this report, which includes all verifications performed against the Producer's serial number information stored in Product Information Manager.

See the information that displays in the Verification History report CSV file.

Guidelines

The CSV file is available for download for up to 7 days. Each request returns a new pre-signed S3 URL, which expires 10 minutes after the time of receipt.

Element Type Description
fileId String Required. The ID of the CSV file containing a Verification History report. The fileId is returned in the Poll Verification History Request Processing response or Query Verification History Requests response.

Example

{
    "t": {
        "v": 1,
        "m": "pie--get-verification-history-report--v1",
        "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C"
    },
    "p": {
        "fileId": "8f996821-fd3f-402a-b3cd-8c5cd32f4e1d"
    }
}

Guidelines

The CSV file is available for download for up to 7 days. Each request returns a new pre-signed S3 URL, which expires 10 minutes after the time of receipt.

Element Type Description
fileUrl String Required. A pre-signed S3 URL. Use this link to download the CSV file containing the Verification History report.
Each pre-signed S3 URL expires after 10 minutes after the time of receipt.

Example

{
    "t": {
        "v": 1,
        "m": "pie--get-verification-history-report-response--v1",
        "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C"
    },
    "p": {
        "fileUrl": "s3://kajsdfpljelj-lakdsflekj"
    }
}