Master data download APIs

Consumers download product master data records from Producers for the Consumers' operational purposes (e.g. distribution). In order to access product master data records, a Producer must make the records available to Consumers.

Download Product Master Data Records (REST)

Consumers use this message to asynchronously download product master data records from Producers. Use the processingId returned in the response to check the status of the download in the Poll Product Master Data Download Processing API.

Download Product Master Data Records request

Guidelines

Element		Type	Description
records		Array	Required. The array containing all shared packaging codes, defined as a code and type. The shareStatus column in the Download Product Master Data Records (CSV) file download indicates whether or not the Producer has granted the Consumer access to the record.
	packagingCode	Integer	Required. The serialized product's packaging code.
	packagingCodeType	Enum	Required. Indicates the type of the serialized product's associated packagingCode. Valid value: `GTIN-14`

Example

{
    "t": {
        "v": 1,
        "m": "pie--consumer-download-mds--v1",
        "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C"
    },
    "p": {
        "records": [
            { "packagingCode": "10312345678910", "packagingCodeType": "GTIN-14" },
            { "packagingCode": "00312345678913", "packagingCodeType": "GTIN-14" }
        ]
    }
}

Download Product Master Data Records response

Guidelines

Element	Type	Description
processingId	String	Required. The unique identifier the Consumer uses in the Poll Product Master Data Download Processing API to check the status of the download request and receive a pre-signed S3 URL link to a CSV file containing the requested product master data records.

Example

{
    "t": {
        "v": 1,
        "m": "pie--consumer-download-mds-response--v1",
        "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C",
        "cid": "9ae3c53b-0b11-4e63-8d0d-79b3731ab1b5"
    },
    "p": {
        "processingId": "8f996822-gd3f-407a-b3cd-8c5cd32f4e1a"
    }
}

Poll Product Master Data Download Records (REST)

Consumers use this message to check the status of the asynchronously processed Download Product Master Data Records API request. Use the processingId returned in the initial Download Product Master Data Records response to check the status of the download.

Poll Product Master Data Download Records request

Guidelines

The token (i.e. fileUrl) returned in the Poll Product Master Data Download Processing response expires 5 minutes after time of receipt.

Element	Type	Description
processingId	String	Required. The unique identifier a Consumer uses to check the status of a download request for product master data.

Example

{
    "t": {
       "v": 1,
       "m": "pie--consumer-poll-processing-mds--v1",
       "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C"
    },
    "p": {
       "processingId": "8f996821-fd3f-402a-b3cd-8c5cd32f4e1d"
    }
}

Poll Product Master Data Download Records response

Guidelines

Element	Type	Description
processingState	String	Required. Reflects one of the following statuses for the download request: `COMPLETE` – Product Information Manager has completed processing the request. The fileUrl is returned for the CSV download. `PENDING` – Product Information Manager has not started processing the request. `PROCESSING` – Product Information Manager has started processing the request, but it is not complete.
fileUrl	Array	A pre-signed S3 URL where the CSV file of product master data records is provided. The file is in the corresponding Master Data Share CSV format for Consumers. When processingState = `COMPLETE`, the fileUrl is present and contains the pre-signed S3 URL link to the product master data records.

Example

{
    "t": {
       "v": 1,
       "m": "pie--consumer-poll-processing-mds-response--v1",
       "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C",
	"cid": "f8222b59-3ddc-45da-a569-f192e310f0fd"	
    },
    "p": {
        "processingState": "COMPLETE",
        "fileUrl": "s3://bucket/path/file.csv"
    }
}

Download Product Master Data Records (CSV)

Guidelines

This CSV file contains the downloaded master data records owned by a Producer in Product Information Manager. The Producer must grant permission for Consumers to be able to download their records.

The Occurs column indicates the min and max occurrence (e.g. 0...1) of a field per record, not for the entire CSV file.

Field	Occurs	Type	Description
additionalTradeItemIdentification	0...*	String	Conditionally required for the US target market. Country drug code.
additionalTradeItemIdentificationTypeCode	0...*	Enum	Conditionally required for the US target market. Country drug code type. See Country Drug Code Type for valid values.
brandOwnerPartyIdentificationValue	0...*	String	Conditionally required for India and EU. Marketing Authorization Holder (MAH) identifier.
co-licensedPartnerIDTypeCode	0...*	String	Co-licensed partner ID code type.
co-licensedPartnerIDValue	0...*	String	Co-licensed partner ID value.
co-licensedPartnerName	0...*	String	Co-licensed partner name.
companyPrefix	1...1	Integer	Conditionally required if the packaging code type is GTIN. The 6- to 12-digit GS1 Company Prefix value unique to your company.
containedPackagingCode	0...1	Integer	For Each or packaging code type of `NTIN`, do not pass in a value. Packaging code.
containedPackagingCodeType	0...1	Enum	For Each or packaging code type of `NTIN`, do not pass in a value. Type of packaging code. See Packaging Code Type for valid values.
dosageFormType	1...*	String	Required. Type of dosage form.
exclusiveDistributorIDTypeCode	0...*	String	Type of exclusive distributor ID.
exclusiveDistributorIDValue	0...*	String	Exclusive distributor ID.
exclusiveDistributorName	0...*	String	Exclusive distributor name.
exemptedFromRegulatoryReporting	1...*	Boolean	Product is exempt from regulatory reporting if value is `true`.
genericName	1...*	Boolean	Conditionally required for the US target market. May indicate the GS1 generic name, functional name, or regulated chemical name.
languageCode	1...*	Enum	The language using the standard two- or three-letter abbreviation specified in ISO 639-1 language code. See Language Code for valid values.
mahIdType	0...*	String	Conditionally required for India and EU. MAH identifier type.
manufacturerOfTradeItemPartyName	1...*	String	Manufacturer name.
netContentDescription	1...1	String	Quantity.
packageTypeCode	1...1	Enum	Packaging Level. See Packaging Level for valid values.
packagingCode	1...1	Integer	Required. Serialization packaging code identifier value for the unit of measure (e.g. each, inner pack, case).
packagingCodeType	1...1	Enum	Required. Enumeration of serialization packaging code identifier types. See Packaging Code Type for valid values.
partyName	0...*	String	Conditionally required for India and EU. Name of the MAH.
productType	1...*	Enum	Enumeration of serialization product code identifier types. See Product Type for valid values.
quantityOfLowestSaleableUnit	1...1	Integer	Required. If Each, the value equals `0`. Lowest saleable unit.
regulatedProductName	1...*	String	Required. Name of the serialized product that falls under the target market's regulatory requirement.
shareStatus	1...1	Enum	Indicates whether or not the user has access to the Producer's product master data record. See Share Status for valid values.
strengthDescription	1...1	String	Required. Strength of the product.
targetMarketCountryCode	1...*	Enum	Required. target market country code. See Country Code for valid values.
totalQuantityOfNextLowerLevelTradeItem	1...1	Integer	Required. If Each, the value equals `0`. Contained quantity.
tradeItemDescription	1...*	String	Required. Description of the product.

Query Product Master Data (REST)

Consumers use this message to query for product master data records which have been made available for download by a Producer who owns the data. Product Information Manager allows users to query against a variety of record details, including date and time, packaging code type, and specified fields.

Query Product Master Data request

Guidelines

Element					Type	Description
query-metadata					Object	Required. Contains the maximum limit and possible fields.
	control				Object	Required. The set of controls that determines how to return the result set back to the requester.
		limit			Integer	Sets the maximum number of records that can be returned per query.
		query-token			String	The token returned in a previous query response that provides access to the next set of results.
	time				Object	Required. The set of parameters that allow query results filtered by time and date.
		past			Object	Allows for the retrieval of all past records, limited by number of records and unit of time.
			amount		Integer	The number of records to return for the given time unit.
			unit		String	The unit of time. Valid values: `DAYS` `HOURS` `MINUTES` `SECONDS` `MILLIS`
		range			Object	Allows for the retrieval of records within a specified range.
			timestamp		Object	Determines the result range by timestamp.
				start	Number	Required. The range start timestamp in UTC-millisec format.
				end	Number	Required. The range end timestamp in UTC-millisec format.
			date-time		Object	Determines the result range by date-time.
				start	String	Required. The range start date-time in YYYY-MM-DDThh:mm:ssTZD format.
				end	String	Required. The range end date-time in YYYY-MM-DDThh:mm:ssTZD format.
			mode		String	Required. Determines whether timestamp or date-time is used. Valid values: `TIMESTAMP` `DATETIME`
		since			Object	Allows for the retrieval of all records starting from a specified time or date.
			timestamp		Number	The timestamp from which records will be returned.
			date-time		String	The date-time from which records will be returned.
			mode		String	Required. Determines whether timestamp or date-time is used. Valid values: `TIMESTAMP` `DATETIME`
		exclusive			Boolean	Determines whether to include or exclude boundary values for the specified time or date range. Set this element to `true` to exclude boundary values. The default value is false (i.e. boundary values are included by default).
		field-name			String	Required. The time field in the object to query against.
		mode			String	Required. Determines which time mode to use in the query. Valid values: `PAST` `RANGE` `SINCE`
	select				Object	The information about the filters that can be applied to a query.
		fields			Array	Each field has a name and an expression that indicates the value being queried.
			name		String	The name of the field in the product master data record to retrieve.
			expression		String	The expression indicating the field in the product master data record to retrieve. Format this element to receive the desired information in the response: `$.<field name>` — Specify the field to return. `$` — Return all fields for any records in the result set.
query-filter					Object	The object containing possible query filters.
	records				Array	The array containing packaging codes to retrieve, defined as a code and type.
		packagingCode			Integer	Required. The serialized product's packaging code.
		packagingCodeType			Enum	Required. Indicates the type of the serialized product's associated packaging code. Valid values: `GTIN-14` `NTIN` `CN-RESCODE` `PPN`
	manufacturerName				String	The name of the Pharmaceutical Manufacturer as it appears on the product label.
	countryDrugCode				String	The country drug code of the product.
	countryDrugCodeType				String	The type of country drug code of the product.
	productName				String	The brand name of the product as it appears on the product label.
	productType				Enum	Indicates the type of product identified on the record. Valid values: `DERIVATIVEPRODUCT`— A derivative drug product. `MEDICALDEVICE`— A medical device. `OTCDRUG` — An over-the-counter drug. `PRESCRIPTIONDRUG` — A prescription drug.
	targetMarketCountryCodes				Array	A list of target market country codes. See Country Code for valid values.
	exemptedFromReporting				Enum	Indicates if the product is subject to or exempt from traceability requirements in the market. Valid values: `EXEMPT` — The product is exempt from traceability requirements in the market. `NOT_EXEMPT` — The product is not exempt from traceability requirements in the market.
	shareStatus				Enum	The share status of the record. Valid values: `SHARED` — The product master data record is accessible in one or more target markets. `NOT_SHARED` — The product master data record is inaccessible in one or more target markets.

Example


{
    "t": {
        "v": 1,
        "m": "pim--consumer-query-mds--v1",
        "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C",
    },
    "p": {
        "query-metadata": {
            "control": {
                "skip": 0,
                "limit": 100,
                "query-token": "aef431"
            },
            "time": {
                "past": {
                    "amount": "2",
                    "unit": "MINUTES"
                },
                "range": {
                    "timestamp": {
                        "start": "1523229645000",
                        "end": "1523229646000"
                    },
                    "date-time": {
                        "start": "2018-04-08T23:28:50Z",
                        "end": "2018-04-08T23:30:50Z"
                    },
                    "mode": "DATETIME"
                },
                "since": {
                    "timestamp": "1523229646000",
                    "date-time": "2018-04-08T23:30:50Z",
                    "mode": "TIMESTAMP"
                },
                "exclusive": false,
                "field-name": "example-field",
                "mode": "SINCE"
            },
            "select": {
                "fields": [
                    {
                        "name": "field-name",
                        "expression": "$.field-name"
                    }
                ]
            }
        },
        "query-filter": {
            "records": [
                {
                    "packagingCode": "17283948271839",
                    "packagingCodeType": "GTIN-14"
                }
            ],
            "productType": "PRESCRIPTION_DRUG",
            "targetMarketCountryCodes": [
                "US"
            ],
            "exemptedFromReporting": "EXEMPT",
            "shareStatus": "SHARED"
        },
    }
}

Query Product Master Data response

Guidelines

Element			Type	Description
query-metadata-response			Object	Required. Contains the query limits and results.
	control		Object	Required. The set of controls that determines how to return the result set back to the requester.
		limit	Integer	Required. The maximum number of records returned in the result set.
		query-token	String	Required. The token returned if records are available that exceed the limit.
		total-results	Integer	Required. The total number of results returned.
results			Array	A list of all records and information in response to the query parameters.

Example

{
    "t": {
        "v": 1,
        "m": "pim--consumer-query-mds-response--v1",
        "app-id": "393C3176-6F7C-438D-B06F-DDCDA21C2E5C",
        "cid": "75589171-3257-4a74-90a8-c441b9accd51"
    },
    "p": {
        "query-metadata-response": {
            "control": {
                "total-results": 1,
                "skip": 1,
                "limit": 100,
		 "query-token": "aef431"
            }
        }
        "results": [
            {}
        ]
    }
}