This endpoint creates a new tag association batch and all the items/tags specified as part of that batch.
Request
Method
POST {data-service}/v3/tag_association_batches
The URL will have a .json, .csv, or .xml filename extension appended to it. This will specify the content-type of the API response. If the filename extension is omitted from the URL, .json will be assumed.Resource
Header
Api-Key: 0123456789ABCDEF Content-Type: application/json
NOTE: An actual body would have either the (tag-issuer-id and tag-quantity) or (epc-list), but not both.
Body
Body Fields
| Field | Data Type | Description |
|---|---|---|
| item_description | object | Required. Defines the attributes of the items in the batch being tagged. |
| formulary_search | object | Required. The key and value supplied within this section will be used to search the user’s “current hospital” formulary on the field specified. The search method is looking for an “exact match” including special characters and capitalization.
Formulary Search: Matching Behavior
|
| field | const | Required. Works in conjunction with the value parameter. The const you set here is the name of the field in the formulary that you’re going to use for searching. In the parlance of key-value pairs, this would be the key.
The const ndc_upc_hri_full is the only supported token at this time. |
| value | string | Required. Works in conjunction with the field parameter. The string you set here is the value that you’re searching for in the formulary, within the field that was already specified. In the parlance of key-value pairs, this would be the value.
ndc_upc_hri_full — The product’s NDC, HRI, or UPC. Hyphens must be included here because the search is for an exact match. |
| lot | string | Required. Null values ok. See note below about lot number and expiration date validation. |
| compound_date | date | Required. Null values ok. |
| expiration_date | object | Required. Null value prohibited for this object (allowed on child fields). See note below about lot number and expiration date validation. |
| manufacturer | date | Required. Null values ok. Specify as YYYY-MM-DD, include leading zeros. |
| refrigeration | date | Required. Null values ok. Specify as YYYY-MM-DD, include leading zeros. |
| multi_dose_open | date | Required. Null values ok. Specify as YYYY-MM-DD, include leading zeros. |
| batch_information | object | Required. Defines attributes about the tags and batch handling. |
| third_party_batch_id | string | Required. Null values ok. If the tagger has an batch identifier in another system, such as an ERP or labeling system, they can enter it here and it can later be surfed in Kit Check reports. |
| tag_restricted | boolean | Required, true or false, not null. |
| epc_generation_method | const | Required. Allowed values: kc, tagger. Consult with your Kit Check representative before selecting a method. Once you select a method, you should never change it; otherwise, you risk an EPC collision.
kc – This specifies that Kit Check will be inventing the EPCs for this batch of items being tagged. Kit Check will increment from the last serial number used, within the context of the appropriate tag issuer ID. For this method, the quantity field is required, and the epc_list field must be null. tagger – This specifies that the tagging party (the caller of this API, typically) is inventing their own EPCs for this batch of items being created. For this method, the quantity field must be null, and the epc_list field is required. |
| tag_quantity | int | (required, if “kc” method) The number of EPCs/tags and items that will be created. If you are creating an additional tag for batch control purposes or other record keeping, please include that tag in this quantity.
If using quantities higher than 500 in a single call, please consult with your Kit Check representative first. |
| tag_list | array [string] | (required, if “tagger” method) The list of EPCs and TIDs of the tag that make up this batch.
TID list accepts 24 hex characters If using quantities higher than 500 in a single call, please consult with your Kit Check representative first. |
| tag_type_id | int | Required, null prohibited. The tag type ID. This is an ID defined by Kit Check, please consult with your Kit Check representative to get this value. |
Body Example
{
"item_description": {
"formulary_search": {
"field": "ndc_upc_hri_full",
"value": "0000-0000-00"
},
"lot": "20150812AA",
"compound_date": "2000-01-01",
"expiration_date": {
"manufacturer": "2099-12-31",
"refrigeration": null,
"multi_dose_beyond_use": null
}
},
"batch_information": {
"third_party_batch_id": "ABC123",
"tag_restricted": false,
"epc_generation_method": "kc",
"tag_quantity": 9999,
"tag_list":[{ "epc": "800100000000000000000000", "tid": "a90a796b5a43688341318743"}, { "epc": "800100000000000000000001", "tid": "0de6d45a1ad95e3017eff59b"}, { "epc": "800100000000000000000002", "tid": "b07b876a4b7154802143265"}],
"tag_type_id": 99 } }
Tag Issuer ID Notes
Background
- The API will infer the user’s “current hospital” from the bearer token.
- Each hospital has 0 or 1 tag issuer IDs.
Behaviour
- If the hospital has no tag issuer ID, the API call will completely fail.
- (NOT YET IMPLEMENTED) If the hospital has a tag issuer ID and the epc-generation-method is tagger, then verify that all EPCs in the epc-list match that hospital’s tag issuer ID. If one or more don’t match, the API call will completely fail.
Lot Number and Expiration Date Validation
If a lot number is specified, the normal validation should occur. That is, for all existing instances of items matching this formulary entry they and lot number, they should have the same manufacturer’s expiration (null or a date value) as the new items attempting to be created by this API call.
Response
HTTP status codes
- 201 Created
- 404 Not Found — Typically 404 is returned when the formulary search returns zero (0) matches.
- 422 Conflict — Represents a wide range of errors. See JSON document in response body for more details on all errors.
Header
Content-Type: application/json
Location: {data-service}/v2/tag_association_batches/0123456789 (NOT YET IMPLEMENTED)
The content-type of the response body is specified in the URL. See description of Request Resource earlier in this document.
Body
If the content-type is CSV, the following should be expected:
- A header row will be included with each field name and each field should be encapsulated in quotes.
- For fields that contain a quotation mark character
", they will be escaped by placing two quotation marks in a row"". - Each line will terminate with a carriage return and a newline character.
Body Fields
| Field | Data Type | Description |
|---|---|---|
| ndc_upc_hri_full | The NDC, HRI, UPC, or other primary identifier for the dictionary entry. | |
| lot | Lot number. | |
| compound_date | Compound date. | |
| expiration_date_manufacturer | Manufacturer’s expiration date. | |
| expiration_date_refrigeration | Beyond-use date related to removal from refrigeration. | |
| expiration_date_multi_dose_beyond_use | Beyond-use date related to the opening or puncturing of a multi-dose vial. | |
| epc_raw | The 24-hex EPC without any special formatting. Useful for encoding the RFID inlay. | |
| epc_formatted | The 24-hex EPC with human-readable formatting. This field must be used if you’re printing the EPC in a user-readable location such as on the tag.
The 24 hex characters are separated by hyphens into groups of 4, 4, 8, 4, and 4 character each, for easier readability. |
Body Example (JSON)
[
{
"ndc_upc_hri_full": "0000-0000-00",
"lot": "20150812AA",
"compound_date": "2000-01-01",
"expiration_date_manufacturer": "2099-12-31",
"expiration_date_refrigeration": null,
"expiration_date_multi_dose_beyond_use": null,
"epc_raw": "800100000000000000000000",
"epc_formatted": "8001-0000-00000000-0000-0000"
}, {
"ndc_upc_hri_full": "0000-0000-00",
"lot": "20150812AA",
"compound_date": "2000-01-01",
"expiration_date_manufacturer": "2099-12-31",
"expiration_date_refrigeration": null,
"expiration_date_multi_dose_beyond_use": null,
"epc_raw": "800100000000000000000000",
"epc_formatted": "8001-0000-00000000-0000-0000"
}, {
"ndc_upc_hri_full": "0000-0000-00",
"lot": "20150812AA",
"compound_date": "2000-01-01",
"expiration_date_manufacturer": "2099-12-31",
"expiration_date_refrigeration": null,
"expiration_date_multi_dose_beyond_use": null,
"epc_raw": "800100000000000000000000",
"epc_formatted": "8001-0000-00000000-0000-0000"
}
]
Example Calls
Request to register 200 items, Kit Check to generate EPCs, response formatted as CSV
{
"item_description": {
"formulary_search": {
"field": "ndc_upc_hri_full",
"value": "0000-0000-00"
},
"lot": "20150812AA",
"compound_date": "2000-01-01",
"expiration_date": {
"manufacturer": "2099-12-31",
"refrigeration": null,
"multi_dose_beyond_use": null
}
},
"batch_information": {
"third_party_batch_id": "ABC123",
"tag_restricted": false,
"epc_generation_method": "kc",
"tag_quantity": 200,
"epc_list": null,
"tag_type_id": 18
}
}
Request to register 3 items, Tagger supplying EPCs, response formatted as CSV
{
"item_description": {
"formulary_search": {
"field": "ndc_upc_hri_full",
"value": "0000-0000-00"
},
"lot": "20150812AA",
"compound_date": "2000-01-01",
"expiration_date": {
"manufacturer": "2099-12-31",
"refrigeration": null,
"multi_dose_beyond_use": null
}
},
"batch_information": {
"third_party_batch_id": "ABC123",
"tag_restricted": false,
"epc_generation_method": "tagger",
"tag_quantity": null,
"epc_list": ["800100000000000000000000", "800100000000000000000001", "800100000000000000000002"],
"tag_type_id": 18
}
}