Description
Allows onboarded customers to submit an Order to Hill Laboratories and get instant feedback on the submission status.
Key Features
- Allows a submitter to request the creation of an Order
- Provides instant validation of data and feedback on submission status
- Ability to provide numerous Order and/or Sample references
- Ability to provide numerous contacts, with varying order roles (Submitter, Primary contact)
- Ability to submit Composite Samples.
- Ability to provide GPS (point or intersect) and named sampling locations
Endpoint
Testing: POST https://cat-api.hill-laboratories.com/client/api/v3/order-requests
Production: POST https://api.hill-laboratories.com/client/api/v3/order-requests
Schema
Testing: https://cat-cdn.hill-laboratories.com/json-schema/client-api/v3/ClientOrder.json
Production: https://cdn.hill-laboratories.com/json-schema/client-api/v3/ClientOrder.json
Request Object
| Field | Value Type | Validation | Description |
|---|---|---|---|
| Order References | Entity | Optional | Array of References supplied by the Customer. Order References should be unique (within an Account), but this is not validated. A valid Order Reference is made up of a pair (name & value) |
| __OrderReference.name | string | * | The label or identifier for the reference. * Required if a paired value is supplied. Cannot be NULL or blank. maxLength = 30. The following reference names are reserved, and if used may appear on the Results Report: ClientRef, AdditionalClientRef, ClientOrderNr. The following reference name is reserved, and if used will apply quoted terms to this order: QuoteNr |
| __OrderReference.value | string | * | The value of the reference for this Order. * Required if a paired name is supplied. maxLength = 64 |
| Organisation/s | Array | Required | The Hill Lab Organisation (or Organisations) that relate to the Order. An array of Hill Lab Organisations (an array labeled “Organisations”) this supports specifying differing owner and charging organisations |
| __Name | string | Optional | The name of this Organisation (used for lookup) Note: If no Name is provided the Order will attach to the Organisation of the Contact with PRIMARY OrderRole |
| __OrderRoles | Array | Required | An array of roles that this Organisation plays for this Order. The mandatory Roles include:”PRIMARY_ORGANISATION” = identifies that this Organisation is ultimately responsible for the existence of this Order”CHARGE_TO” = identifies that this Organisation is to be invoiced for any charges that result from this Order.Notes:An Order must have a PRIMARY_ORGANISATION, but does not need a CHARGE_TO. Where there is both a PRIMARY_ORGANISATION and CHARGE_TO, these don’t have to be on the same Organisation (I.e. one Organisation can be OWNER, another can be CHARGE_TO) |
| __Contacts | Entity | Required | A collection of Contacts (within an Organisation) that relate to the Order |
| ____OrderRoles | Array | Required | An array of roles that this Contact plays for this Order. The mandatory Roles include:”SUBMITTER” = identifies that this Contact placed this Order”PRIMARY” = identifies that this Contact is the primary contact for this Order, and by default will receive communications about this Order.Note: An Order must have a SUBMITTER and a PRIMARY, but these roles don’t have to be on the same Contact (i.e. one Contact can be SUBMITTER, another can be PRIMARY) |
| ____FirstName | string | ** | (Email, LastName and FirstName) is treated as a Lookup set |
| ____LastName | string | ** | (Email, LastName and FirstName) is treated as a Lookup set |
| ____Email | string | ** | (Email, LastName and FirstName) is treated as a Lookup set |
| __Addresses | Entity | Optional | A collection of Addresses (within an Account) that relate to the Order – I.e. the Delivery and Invoice addressesBoth Addresses will default to those of the Primary Contact if none are suppliedDelivery Address is required if Sampling Supplies are to be shipped to an Address other than the Default Delivery Address of the Primary Contact’s Account |
| ____Address1 | string | Required | maxLength = 40 |
| ____Address2 | string | Optional | maxLength = 40 |
| ____City | string | Required | maxLength = 40 |
| ____Postcode | string | Required | maxLength = 10 |
| ____Country | string | Required | maxLength = 40 |
| ____OrderRoles | Array | Required if supplied | An array of roles that this Address plays for this Order. The Roles include:”DELIVERY” = Required if a Sampling Supplies Order Line exists”INVOICE” = Optional |
| Notes | string | Optional | Textual instructions to provide additional information to the OrdermaxLength = 2000 |
| Order Lines | Array | Required | **** Each Order will contain one or more Order Lines – each being either:SamplingSupplies,Sample, orCompositeSampleMax items = 200 |
| __Sampling Supplies | Entity | **** | A Sampling Supply Order Line points to a ‘Product’ which can be ordered. This is a simple entity with an Item Code and Quantity |
| ____Code | string | Required | The Hill Labs Catalogue Item Code of the product orderedmaxLength = 32 |
| ____Quantity | number | Required | The quantity of the product orderedMaximum value = 100 |
| __Sample | Entity | **** | A Sample Order Line points to an array of Analytical Tests to be processed on a single sample.The Sample will describe itself (via a Sample_Type identifier), and then the Analytical Tests to be performed |
| ____Name | string | Required | Textual identifier for the SamplemaxLength = 255 |
| ____DateTime | string | Optional | timestamp (ISO format: yyyy-mm-ddThh:mm:ss.ffffff) for when the sample was collected (in UTC) |
| ____SampleType | Entity | Required | A definition of the Substance which is to be tested |
| ______SampleTypeCode | string | Required | The Hill Labs Sample Type Code that defines the Substance type of the sample |
| ______SampleAttributes | Array | Optional | An array of value pairs that better define the Sample Type to be tested. There is a set list of valid SampleType Attributes for each Substance in the Hill Labs substance tree. Invalid pairs will result in Order failure. |
| ________AttributeName | string | The label or identifier for the attribute.* Required if a paired value is supplied.Cannot be NULL or blankmaxLength = 100 | |
| ________AttributeValue | string | The value of the attribute.* Required if a paired value is supplied.Can be NULL or blankmaxLength = 100 | |
| ____Location | Entity | Optional | Point or Intersect defining where the sample was collectedA Point will have one Lat/Long recordAn Intersect will have more than one Lat/Long record |
| ______Point/Intersect.Latitude | number | Optional | Required if Point/Intersect.Longitude is provided. |
| ______Point/Intersect.Longitude | number | Optional | Required if Point/Intersect.Latitude is provided. |
| ______Name | string | Optional | maxLength = 50 |
| References | Array | Optional | Allows users to specify references that will be available in results published by the API. |
| ______Name | string | maxLength = 30 | |
| ______Value | string | maxLength = 64 | |
| Containers | Array | Optional | Multiple containers may be specified |
| ______Barcode | Entity | ||
| ________Type | string | ***** | Enumerated value to define what type of barcode is recorded’LINEAR’ = “one dimensional” barcode that, when rendered, is made up of lines and spaces of various widths that create specific patterns***** Required if a paired value is supplied. |
| ________Value | string | ***** | Barcode value***** Required if a paired type is supplied. |
| ____AnalyticalTests | Array | Required | An Analytical Test Order Line must have at least one Analytical Test |
| ______Code | string | Required | The Hill Labs Analytical Test Catalogue Item Code that defines the Test to be performed on the SamplemaxLength = 32 |
| SampleParameters | Array | Optional | Array of parameters to be supplied for samples that contain certain analytical test, e.g. UMFCert. These should not be passed for any other analytical test codes.Note: Currently this is only available for the specific test “UMFCert”. Should you require this be available for additional testing, we can work to stand these up during the onboarding process. |
| ParameterCode | string | Required | The code for a sample parameter, e.g. “BatchNumber”minLength = 1maxLength = 255 |
| ParameterValue | ****** | Required | The value for a sample parameter, e.g. “100”minLength = 0maxLength = 255****** A String or Numeric value as configured in the Hill Labs system |
Required Headers
“Content-Type”: “application/json”
“Authorization”, “Bearer Add Your Authentication Token here“
Example Submissions
Below are some examples for order submissions, these cover a variety of use cases
Generic Use Cases
A single sample, in a barcoded container, requesting an Analytical Test
Order Submission – Single Sample, Single Test
{
"orderReferences":[
{
"name":"ClientRef",
"value":"Test"
}
],
"organisations":[
{
"orderRoles":[
"PRIMARY_ORGANISATION",
"CHARGE_TO"
],
"contacts":[
{
"orderRoles":[
"PRIMARY",
"SUBMITTER"
],
"lastName":"Smith",
"firstName":"John",
"email":"my.email@mybusiness.com"
}
],
"addresses":[
{
"address1":"1023 Rocky Road",
"city":"Smalltown",
"country":"New Zealand",
"postCode":"1234",
"orderRoles":[
"INVOICE"
]
}
]
}
],
"notes":"Single Sample, Single Test Example",
"lines":[
{
"sample":{
"name":"Selenium",
"sampleType":{
"sampleTypeCode":"CLOVER|P3",
"sampleAttributes":[
]
},
"containers":[
{
"barcode":{
"type":"LINEAR",
"value":"331000242128"
}
}
],
"analyticalTests":[
{
"code":"Se"
}
]
}
}
]
}An order for Supplied Items
Order Submission – Supplied Item
{
"orderReferences":[
{
"name":"ClientRef",
"value":"Test001"
}
],
"organisations":[
{
"orderRoles":[
"PRIMARY_ORGANISATION"
],
"contacts":[
{
"orderRoles":[
"SUBMITTER",
"PRIMARY"
],
"lastName":"Smith",
"firstName":"John",
"email":"my.email@mybusiness.com"
}
]
}
],
"notes":"My notes to the lab",
"lines":[
{
"samplingSupplies":{
"code":"HoneyKit",
"quantity":10
}
},
{
"samplingSupplies":{
"code":"PlantBag",
"quantity":5
}
}
]
}An order with multiple references
Order Submission – Multiple order references
{
"orderReferences":[
{
"name":"ClientRef",
"value":"my client reference"
},
{
"name":"AdditionalClientRef",
"value":"additional reference"
},
{
"name":"ClientOrderNr",
"value":"my order number"
},
{
"name":"QuoteNr",
"value":"1234"
}
],
"organisations":[
{
"orderRoles":[
"PRIMARY_ORGANISATION",
"CHARGE_TO"
],
"contacts":[
{
"orderRoles":[
"PRIMARY",
"SUBMITTER"
],
"lastName":"Smith",
"firstName":"John",
"email":"my.email@mybusiness.com"
}
],
"addresses":[
{
"address1":"1023 Rocky Road",
"city":"Smalltown",
"country":"New Zealand",
"postCode":"1234",
"orderRoles":[
"INVOICE"
]
}
]
}
],
"notes":"",
"lines":[
{
"sample":{
"name":"Selenium",
"sampleType":{
"sampleTypeCode":"CLOVER|P3",
"sampleAttributes":[
]
},
"containers":[
{
"barcode":{
"type":"LINEAR",
"value":"331000242128"
}
}
],
"analyticalTests":[
{
"code":"Se"
}
]
}
}
]
}An order with multiple sample references
Order Submission – Multiple sample references
{
"orderReferences":[
{
"name":"ClientRef",
"value":"Test"
}
],
"organisations":[
{
"orderRoles":[
"PRIMARY_ORGANISATION",
"CHARGE_TO"
],
"contacts":[
{
"orderRoles":[
"PRIMARY",
"SUBMITTER"
],
"lastName":"Smith",
"firstName":"John",
"email":"my.email@mybusiness.com"
}
],
"addresses":[
{
"address1":"1023 Rocky Road",
"city":"Smalltown",
"country":"New Zealand",
"postCode":"1234",
"orderRoles":[
"INVOICE"
]
}
]
}
],
"notes":"",
"lines":[
{
"sample":{
"name":"Sample 1",
"references":[
{
"name":"clientSampleID1",
"value":"My client sample ID value 1"
},
{
"name":"clientSampleID2",
"value":"My client sample ID value 2"
}
],
"sampleType":{
"sampleTypeCode":"HoneyD",
"sampleAttributes":[
]
},
"containers":[
{
"barcode":{
"type":"LINEAR",
"value":"33194719211"
}
}
],
"analyticalTests":[
{
"code":"Honey3in1"
}
]
}
}
]
}An order for an Analytical Test with a sample spanning two containers
Order Submission – Multiple containers for a sample
{
"orderReferences":[
{
"name":"ClientRef",
"value":"Test"
}
],
"organisations":[
{
"orderRoles":[
"PRIMARY_ORGANISATION",
"CHARGE_TO"
],
"contacts":[
{
"orderRoles":[
"PRIMARY",
"SUBMITTER"
],
"lastName":"Smith",
"firstName":"John",
"email":"my.email@mybusiness.com"
}
],
"addresses":[
{
"address1":"1023 Rocky Road",
"city":"Smalltown",
"country":"New Zealand",
"postCode":"1234",
"orderRoles":[
"INVOICE"
]
}
]
}
],
"notes":"",
"lines":[
{
"sample":{
"name":"Selenium",
"sampleType":{
"sampleTypeCode":"CLOVER|P3",
"sampleAttributes":[
]
},
"containers":[
{
"barcode":{
"type":"LINEAR",
"value":"331000242128"
}
},
{
"barcode":{
"type":"LINEAR",
"value":"331000242130"
}
}
],
"analyticalTests":[
{
"code":"Se"
}
]
}
}
]
}An order for Analytical Tests with spatial data, Sampling Supply Items and providing a delivery address
Order Submission – Analytical Test & Sampling Supplies, giving delivery address
{
"orderReferences":[
{
"name":"ClientRef",
"value":"my client reference"
}
],
"organisations":[
{
"orderRoles":[
"PRIMARY_ORGANISATION"
],
"contacts":[
{
"orderRoles":[
"SUBMITTER",
"PRIMARY"
],
"lastName":"Smith",
"firstName":"John",
"email":"my.email@mybusiness.com"
}
],
"addresses":[
{
"address1":"1023 Rocky Road",
"city":"Smalltown",
"country":"New Zealand",
"postCode":"1234",
"orderRoles":[
"DELIVERY"
]
}
]
}
],
"notes":"My notes to the lab",
"lines":[
{
"sample":{
"name":"Test1",
"sampleType":{
"sampleTypeCode":"SILAGE|P162"
},
"dateTime":"2018-06-15T20:16:30.449Z",
"containers":[
{
"barcode":{
"type":"LINEAR",
"value":"331000242126"
}
}
],
"location":{
"point":{
"latitude":-37.734485,
"longitude":175.401761
},
"name":"Silage Shed 1, Bale 3"
},
"analyticalTests":[
{
"code":"Silage"
}
]
}
},
{
"sample":{
"name":"Test2",
"sampleType":{
"sampleTypeCode":"SILAGE|P162"
},
"dateTime":"2018-06-15T20:16:30.449Z",
"containers":[
{
"barcode":{
"type":"LINEAR",
"value":"033154024555"
}
}
],
"location":{
"point":{
"latitude":-37.734485,
"longitude":175.401761
},
"name":"Silage Shed 1, Bale 8"
},
"analyticalTests":[
{
"code":"Silage"
}
]
}
},
{
"sample":{
"name":"Test3",
"sampleType":{
"sampleTypeCode":"SOILPAS|S180",
"sampleAttributes":[
{
"attributeName":"Depth (mm)",
"attributeValue":"0-150"
},
{
"attributeName":"Soil Type",
"attributeValue":"Peat"
}
]
},
"dateTime":"2018-06-15T20:16:30.449Z",
"containers":[
{
"barcode":{
"type":"LINEAR",
"value":"331000242127"
}
}
],
"location":{
"intersect":[
{
"latitude":-37.734485,
"longitude":175.401761
},
{
"latitude":-37.97516,
"longitude":175.39941
}
],
"name":"Paddock F, line 2"
},
"analyticalTests":[
{
"code":"BS"
},
{
"code":"B|Soil"
},
{
"code":"AN"
}
]
}
},
{
"samplingSupplies":{
"code":"SoilBag",
"quantity":25
}
},
{
"samplingSupplies":{
"code":"AugAg",
"quantity":1
}
}
]
}Request for Composite Testing
Order submissions for Analytical Tests with composites
- Currently only available for Tutin and Meth
Order Submission – Analytical Test with composites – Meth
{
"organisations":[
{
"orderRoles":[
"PRIMARY_ORGANISATION",
"CHARGE_TO"
],
"contacts":[
{
"orderRoles":[
"PRIMARY",
"SUBMITTER"
],
"lastName":"Smith",
"firstName":"John",
"email":"my.email@mybusiness.com"
}
]
}
],
"notes":"Meth Comp",
"lines":[
{
"sample":{
"name":"SAMPLE 1",
"sampleType":{
"sampleTypeCode":"WIPE|cMiscWipe"
}
},
"containers":[
{
"barcode":{
"type":"LINEAR",
"value":"331000242128"
}
}
]
},
{
"sample":{
"name":"SAMPLE 2",
"sampleType":{
"sampleTypeCode":"WIPE|cMiscWipe"
}
},
"containers":[
{
"barcode":{
"type":"LINEAR",
"value":"331000242128"
}
}
]
},
{
"sample":{
"name":"SAMPLE 3",
"sampleType":{
"sampleTypeCode":"WIPE|cMiscWipe"
}
},
"containers":[
{
"barcode":{
"type":"LINEAR",
"value":"331000242128"
}
}
]
},
{
"sample":{
"name":"SAMPLE 4",
"sampleType":{
"sampleTypeCode":"WIPE|cMiscWipe"
}
},
"containers":[
{
"barcode":{
"type":"LINEAR",
"value":"331000242128"
}
}
]
},
{
"sampleComposite":{
"samples":[
"SAMPLE 1",
"SAMPLE 2",
"SAMPLE 3",
"SAMPLE 4"
],
"name":"",
"analyticalTests":[
{
"code":"Meth_CompR"
}
]
}
}
]
}Order Submission – Analytical Test with composites – Honey
{
"organisations":[
{
"orderRoles":[
"PRIMARY_ORGANISATION",
"CHARGE_TO"
],
"contacts":[
{
"orderRoles":[
"PRIMARY",
"SUBMITTER"
],
"lastName":"Smith",
"firstName":"John",
"email":"my.email@mybusiness.com"
}
]
}
],
"notes":"Honey Comp",
"lines":[
{
"sample":{
"name":"SAMPLE 1",
"sampleType":{
"sampleTypeCode":"HoneyD"
},
"containers":[
{
"barcode":{
"type":"LINEAR",
"value":"331000242126"
}
}
]
}
},
{
"sample":{
"name":"SAMPLE 2",
"sampleType":{
"sampleTypeCode":"HoneyD"
},
"containers":[
{
"barcode":{
"type":"LINEAR",
"value":"331000242127"
}
}
]
}
},
{
"sample":{
"name":"SAMPLE 3",
"sampleType":{
"sampleTypeCode":"HoneyD"
},
"containers":[
{
"barcode":{
"type":"LINEAR",
"value":"331000242128"
}
}
]
}
},
{
"sample":{
"name":"SAMPLE 4",
"sampleType":{
"sampleTypeCode":"HoneyD"
},
"containers":[
{
"barcode":{
"type":"LINEAR",
"value":"331000242129"
}
}
]
}
},
{
"sampleComposite":{
"samples":[
"SAMPLE 1",
"SAMPLE 2",
"SAMPLE 3",
"SAMPLE 4"
],
"name":"",
"analyticalTests":[
{
"code":"TutinComp_RLP"
}
]
}
}
]
}Request for Honey UMF Certificate
Honey Analytical Test with sample parameters
{
"organisations":[
{
"orderRoles":[
"PRIMARY_ORGANISATION",
"CHARGE_TO"
],
"contacts":[
{
"orderRoles":[
"PRIMARY",
"SUBMITTER"
],
"lastName":"Smith",
"firstName":"John",
"email":"my.email@mybusiness.com"
}
]
}
],
"notes":"Honey UMFCert with sample parameters",
"lines": [
{
"sample": {
"name": "SAMPLE 1",
"sampleType": {
"sampleTypeCode": "HoneyD"
},
"containers": [
{
"barcode": {
"type": "LINEAR",
"value": "331000242126"
}
}
],
"analyticalTests": [
{
"code": "UMFCert"
}
],
"sampleParameters": [
{
"parameterCode": "UMFLicence",
"parameterValue": "9999"
},
{
"parameterCode": "BatchNumber",
"parameterValue": "9999"
},
{
"parameterCode": "ExpectedGrade",
"parameterValue": "50"
},
{
"parameterCode": "BatchWeight",
"parameterValue": "9999"
}
]
}
}
]
}Example Response
Upon a successful submission the API will supply an orderId response, below is an example
OrderSummaries Response
{
"orderId": 989
}