MTL_API.md

Molecular Testing Labs API documentation

Table of Contents

1. Authentication
2. Orders
3. Notifications
4. Cancel Orders
5. Test Results
6. Add Additional Tests
7. Patient Info
8. Register Kit
9. Register Code
10. Appendix

Authentication

All requests need the following options in Header:

Key	Value
Content-Type:	application/json
user:	must register an account in MTL first, then use practice/distributor id that MTL provides
token:	MTL provides GUID after registration is completed.

Orders

Create Order

For a client to place orders

URL : /PlaceOrder

Method : POST

Auth required : YES

Example Body

[{
	"shipping_info": {
		"first_name": "John",
		"last_name": "Doe",
		"address_1": "123 Big Road",
		"address_2": "",
		"city": "Vancouver",
		"state": "WA",
		"postcode": "98684",
		"country": "USA"
	},
	"order_number": "123123",
	"ordered_date": "2018-07-09T19:53:08.885569Z ",
	"gender": "male",
	"date_of_birth": "1962-06-03",
	"email": "[email protected]",
	"phone": "123-842-9999",
	"shipping_method": 7,
	"panel_id": [ 26,27 ],
	"physician_id": 1234,
	"lob": "SC",
	"fulfillment": true,
	"kit_id": null,
	"patient_signature": null,
	"insurance":{
		"dx_code":"L23.3,Z99.0",
		"payer":"BCBS ALABAMA",
		"member_id":"VVA20180713",
		"group_number":"1000713",
		"claims_address":"123 Big Rd. Vancouver, WA 98684",
		"is_primary_insured":"1",
		"primary_first_name":"",
		"primary_last_name":"",
		"primary_gender":"",
		"primary_dob":"",
		"primary_relationship":"self",
		"primary_address_1":"",
		"primary_address_2":"",
		"primary_city":"",
		"primary_state":"",
		"primary_zip":""
	},
	"pwn_req_number":"",
	"replacement":{
		"origin_order_number": null
	}
}]

Object Notes

Variable	Expected Type	Notes
order_number	string	a unique id for a client and MTL to communicate with.
physician_id	number	provided after registration with MTL, includes LIS portal access (user name & password)
practice_id	number	provided after registration with MTL. If you are a distributor, this would be your distributor id as well for accessing API
panel_id	array	tests to be ordered - see Example Test Codes
lob	string	line of business: SC - Self Collect DNA FIT - Fitness CGx - Cancer Genomics ID - Infectious Disease
shipping_method	number	7 - standard, 8 - express, 9 – USPS first class (CGX)
fulfillment	boolean	set to true if Molecular needs to ship kit to the patient
kit_id	number	required when “fulfillment” set to false please make kit_id length within 10 digits
patient_signature	boolean	required for DNA/FIT retail kit order(a client fulfill kits by themselves)
pwn_req_number	number	for SC use, MTL sends a copy of test result of PWN when the field has a value
replacement		for SC use, only charge for kit/fulfill/shipping origin_order_number is required if it’s a replacement order.
plan_code	string	for BCBSA use

Example Test Codes

LOB	Panel ID	Panel List
SC	26	Gonorrhea
SC	27	Chlamydia
SC	56	Hep B (DBS), Creatinine (DBS), HIV
SC	45	Creatining (DBS), HIV
DNA	40	Cardiovascular
FIT	36	Fitness DNA
CGX	65	CGx Base
ID	87	Flu

Required Fields

Variable	Notes
order_number
phone
email
gender
date_of_birth
panel_id
physician_id
practice_id
lob
kit_id	required when a client fulfill the kit by themselves
patient_signature	required when a client fulfill DNA kit by themselves
ordered_date
pwn_req_no	required for a client needs STD results to be sent to PWN
shipping_info
insurance	required for an insurance order

Responses

If a client places multi-orders at one time, MTL will reply status for each order.

Example Success Response

{
	"order_number": "123123",
	"success": true,
	"error_msg": null
}

Example Failure Response

{
	"order_number": "234234",
	"success": false,
	"error_msg": "Duplicated order number."
}

The list of error_msg for placing an order :

• Invalid LOB
• Order number is required.
• Duplicated order number.
• Invalid physician id.
• Missing/Invalid panel id.
• Errors when creating patient demographic.

Notifications

Check order status

Retrieve Order Information

URL : /Notifications

URL Parameters :

Parameter	Required	Accepted Values
lob	x	SC, ID, DNA, FIT & CGX
type	x	kit_shipped, kit_received, kit_rejected
order_number		to request notification for all orders when there’s no order_number provided

Method : GET

Auth required : YES

Kit shipped notification

?type="kit_shipped"

[{
	"order_number": "123123",
	"accession_number":"M000031828",
	"type": "kit_shipped",
	"data": {
		"outbound": "0458497584974311111",
		"inbound": "4075498798437922222",
		"shipped_datetime": "2018-01-11T19:53:08.885569Z",
		"kit_reg_code": null
	}
}]

kit_req_code is a 2nd identifier for kit registration use when it’s needed, it combines with 8 digits of characters & numbers, ex: Ei8gi2nA.

Kit received notification

?type="kit_received"

[{
	"order_number": "123123",
	"accession_number":"M000031828",
	"type": "kit_received",
	"data": {
		"received_datetime": "2018-01-11T19:53:08.885569Z"
	}
}]

Sample rejected notification

?type="kit_rejected"

[{
	"order_number": "123123",
	"accession_number":"M000031828",
	"type": "kit_rejected",
	"data": {
		"rejected_datetime": "2018-01-11T19:53:08.885569Z",
		"rejected_reason": " Lacking required specimen quantity"
		"recoverable": false
	}
}]

recoverable can be null when the rejection is not defined as recoverable or not.

Remove Orders from Notification List

URL : /Notifications

URL Parameters :

Parameter	Required	Accepted Values
lob	x	SC, ID, DNA, FIT & CGX
type	x	kit_shipped, kit_received, kit_rejected
order_number	x	order number used when placing an order

Method : PUT

Auth required : YES

Receive Order Information

A client needs to provide an endpoint (url) for Molecular to set up where to send to notification to, it provides basic authentication for the request, user & token are provided by Molecular(same user & token in Authentication).

URL : client defined

Method : POST

Auth required : YES

• Content-Type : application/json

{
	"order_number": "string",
	"accession_number": "string",
	"type": "string",
	"ship_info": {
		"outbound": "string",
		"inbound": "string",
		"shipped_datetime": "string",
		"kit_reg_code": "string"
	 },
	"rcvd_info": {
		"received_datetime": "string"
	 },
	 "rej_info": {
		 "rejected_datetime": "string",
		 "rejected_reason": "string",
		 "recoverable": true
	},
	"report_ready_info": {
		"report_sent_datetime": "string"
	}
}

Kit shipped notification example

{
	"order_number": "123123",
	"accession_number":"M000031828",
	"type": "kit_shipped",
	"ship_info": {
		"outbound": "1111497584974311111",
		"inbound": "1111498798437922222",
		"shipped_datetime": "2018-01-11T19:53:08.885569Z",
		"kit_reg_code": null
	},
	"rcvd_info": null,
	"rej_info": null,
	"report_ready_info": null
}

Kit shipped notification example

{
	"order_number": "123123",
	"accession_number":"M000031828",
	"type": "kit_shipped",
	"ship_info": {
		"outbound": "1111497584974311111",
		"inbound": "1111498798437922222",
		"shipped_datetime": "2018-01-11T19:53:08.885569Z",
		"kit_reg_code": null
	},
	"rcvd_info": null,
	"rej_info": null,
	"report_ready_info": null
}

Kit received example

{
	"order_number": "123123",
	"accession_number": "M000057021",
	"type": "kit_received",
	"ship_info": null,
	"rcvd_info": {
		"received_datetime": "2018-11-09T08:00:00.000Z"
	},
	"rej_info": null,
	"report_ready_info": null
}

Kit rejected example

{
	"order_number": "123123",
	"accession_number": "F000057212",
	"type": "kit_rejected",
	"ship_info": null,
	"rcvd_info": null,
	"rej_info": {
		"rejected_datetime": "2018-11-13T19:33:04.823Z",
		"rejected_reason": "No patient identifiers listed on the sample container / envelope.",
		"recoverable": true
	},
	"report_ready_info": null
}

Report ready example

{
	"order_number": "123123",
	"accession_number": "M000057021",
	"type": "report_ready",
	"ship_info": null,
	"rcvd_info": null,
	"rej_info": null,
	"report_ready_info": {
		"report_sent_datetime": "2018-11-12T08:13:38.827Z"
	}
}

Cancel Orders

Cancel Order

URL : /CancelOrder

URL Parameters :

Parameter	Required	Accepted Values
lob	x	SC, ID, DNA, FIT & CGX
order_number	x	order number used when placing an order

Method : PUT

Auth required : YES

Responses

Example Success Response

{
	"order_number": "1234",
	"success": true,
	"error_msg": null,
	"current_status": "cancelled"
}

Example Failure Response

{
	"order_number": "1234",
	"success": false,
	"error_msg": "can't be cancelled due to it's in process",
	"current_status": "in process"
}

Cancellation Billing Policies

• Before fulfillment – no charge
• After fulfillment but before receiving it at the lab – charge kit & fulfillment fee
• After receiving - the order can’t be cancelled after it’s been processed

Test Results

For retrieving a list of test result ready orders

URL : /TestResult

URL Parameters :

Parameter	Required	Accepted Values
lob	x	SC, ID, DNA, FIT & CGX
order_number		order number used when placing an order

Method : GET

Auth required : YES

List All Orders With Reports Ready

[
	"1234",
	"2234"
]

only list order_number for the orders that have test result ready for reported last 7 days.

Retrieve Test Result Details

?lob="SC"&order_number="1234"

Responses

Example Failure Response

{
	"order_number": "1234",
	"success": false,
	"error_msg": null,
	"current_status": "in process"
}

current_status– includes “not received yet”, “in process”, “rejected”, “cancelled” & “report ready”

Example Success Response

Only reply "success"=true, when test results are ready

SC Success

{
	"order_number": "123123",
	"accession_number": " M000000001",
	"success": true,
	"current_status": "report ready",
	"patient_date_of_birth": "1976-01-01",
	"report_sent_datetime": "2018-06-12T23:15:24.017Z",
	"observations": [
		{
			"test_id": 16,
			"test_name": "Chlamydia trachomatis (CT)",
			"result": "Not Detected",
			"snp": """",
			"result_value": "",
			"assay_datetime": ""
		},
		{
			"test_id": 8,
			"test_name": "Neisseria gonorrhea (NG)",
			"result": "Not Detected",
			"snp": """",
			"result_value": "",
			"assay_datetime": ""
		},
		{
			"test_id": 9,
			"test_name": "Trichomonas vaginalis (TV)",
			"result": "Not Detected",
			"snp": """",
			"result_value": "",
			"assay_datetime": ""
		},
		{
			"test_id": 38,
			"test_name": "Human Immunodeficiency Virus (HIV)",
			"result": "Not Detected",
			"snp": """",
			"result_value": "",
			"assay_datetime": ""
		},
		{
			"test_id": 36,
			"test_name": "Hepatitis C Virus (HCV)",
			"result": "Not Detected",
			"snp": """",
			"result_value": "",
			"assay_datetime": ""
		},
		{
			"test_id": 30,
			"test_name": "Herpes Simplex Virus, type II (HSV2)",
			"result": "Not Detected",
			"snp": "",
			"result_value": "",
			"assay_datetime": ""
		},
		{
			"test_id": 31,
			"test_name": "Syphilis",
			"result": "Not Detected",
			"snp": "",
			"result_value": "",
			"assay_datetime": ""
		}
	],
	"attachments": [{
		"file_name": " M000000001_06122018031248.pdf",
		"content_type": "application/pdf",
		"data": "Base 64 encode"
	}]
}

DNA Success

raw data/report will be provided based on the contract.

{
	"order_number": "123123",
	"accession_number": " DE00000001",
	"success": true,
	"current_status": "report ready",
	"patient_date_of_birth": "1976-01-01",
	"report_sent_datetime": "2018-06-12T23:15:24.017Z",
	"observations": [
		{
			"test_id": 21,
			"test_name": "ANKK1",
			"result": "G/G",
			"snp": "rs1800497",
			"result_value": "",
			"assay_datetime": ""
		},
		{
			"test_id": 12,
			"test_name": "COMT",
			"result": "A/G",
			"snp": "rs4680",
			"result_value": "",
			"assay_datetime": ""
		},
		{
			"test_id": 56,
			"test_name": "DBH",
			"result": "C/C",
			"snp": "rs1611115",
			"result_value": "",
			"assay_datetime": ""
		},
		{
			"test_id": 14,
			"test_name": "OPRM1",
			"result": "A/A",
			"snp": "rs1799971",
			"result_value": "",
			"assay_datetime": ""
		}
	],
	"attachments": [
		{
			"file_name": " DE00000001_Addiction_1007.pdf",
			"content_type": "application/pdf",
			"data": "Base 64 encode"
		},
		{
			"file_name": " DE00000001_Cardiovascular_1007.pdf",
			"content_type": "application/pdf",
			"data": "Base 64 encode"
		}
	]
}

FIT/CGx Success

only report will be provided for Fitness orders

{
	 "order_number": "123123",
	 "accession_number": " PH00000001",
	 "success": true,
	 "current_status": "report ready",
	 "patient_date_of_birth": "1976-01-01",
	 "report_sent_datetime": "2018-06-12T23:15:24.017Z",
	 "observations": [ ],
	 "attachments": [
		{
			"file_name": " PH00000001_1007.pdf",
			"content_type": "application/pdf",
			"data": "Base 64 encode"
		}
	]
}

ID Success

tempstrip_status – includes Ok, Overheated, Frozen & Not Used (no tag in the kit), only has value in ID.

{
	"order_number": "0002",
	"accession_number": "ID19012198",
	"success": true,
	"current_status": "report ready",
	"patient_date_of_birth": "1962-06-03",
	"report_sent_datetime": "2019-10-18T22:47:49.393Z",
	"tempstrip_status": "Ok",
	"observations": [
		{
			"test_id": 295,
			"test_name": "Flu A",
			"result": "Detected",
			"snp": "",
			 "result_value": "31.1",
			 "assay_datetime": "2019-10-18T22:47:49.393Z"
		},
		{
			"test_id": 296,
			"test_name": "Flu B",
			"result": "Detected",
			"snp": "",
			 "result_value": "31.1",
			 "assay_datetime": "2019-10-18T22:47:49.393Z"
		},
		{
			"test_id": 297,
			"test_name": "RSV",
			"result": "Not Detected",
			"snp": "",
			 "result_value": "",
			 "assay_datetime": ""
		}
	],
	"attachments": [
		{
			"file_name": "ID_MockReport.pdf",
			"content_type": "application/pdf",
			"data": " Base 64 encode"
		}
	]
}

Add Additional Tests

For a client to add new tests for the existing orders.

URL : /AddNewTest

Method : PUT

Auth required : YES

Example Body

[{
	"order_number": "123123",
	"origin_panel_id": [ 26,27 ],
	"add_panel_id": [ 4,5 ],
	"lob": "SC"
}]

Responses

If a client places multi-orders at one time, MTL will reply status for each order.

Success

If MTL has NOT received the kit yet and will be able to add the new tests right away.

Example Response

[{
	"order_number": "123123",
	"success": true,
	"error_msg": null,
	"added": true,
	"status": null
}]

If MTL received the kit, and will need technicians to check if the sample has sufficient quantity for new tests.

Example Response

[{
	"order_number": "123123",
	"success": true,
	"error_msg": null,
	"added": false,
	"status": "waiting for approval"
}]

Example Failure Response

[{
	"order_number": "123123",
	"success": false,
	"error_msg": "Order number doesn’t exist.",
	"added": false,
	"status": null
}]

Check the Status of "waiting for approval" Orders

URL : /AddNewTest

Method : GET

URL Parameters :

Parameter	Required	Accepted Values
lob	x	SC

Auth required : YES

Example Response

[
	{
		"order_number": "0003",
		"added": false,
		"status": "Waiting for approval.",
		"approved": false,
		"rejected": false,
		"rejection_reason": null
	},
	{
		"order_number": "0005",
		"added": false,
		"status": null,
		"approved": false,
		"rejected": true,
		"rejection_reason": "Quantity Not Sufficient"
	},
	{
		"order_number": "0006",
		"added": true,
		"status": null,
		"approved": true,
		"rejected": false,
		"rejection_reason": null
	}
]

Patient Info

Interact with Patient Object

Update Patient Info

URL : /Patient

Method : PUT

URL Parameters :

Parameter	Required	Accepted Values
lob	x	DNA, FIT, SC & CGX

Auth required : YES

Example Body

{
	"patient_info": {
		"first_name": "John",
		"last_name": "Doe",
		"address_1": "123 Big Road",
		"address_2": "",
		"city": "Vancouver",
		"state": "WA",
		"postcode": "98684",
		"country": "USA",
		"gender": "male",
		"date_of_birth": "1962-06-03",
		"email": "[email protected]",
		"phone": "123-842-9999"
	},
	"order_number": "0200001",
	"lob": "CGX"
}

pwn_req_number is only for SC

Response

{
	"order_number": "0200001",
	"success": true,
	"error_msg": null
}

Retrieve Patient Info

URL : /Patient

Method : GET

URL Parameters :

Parameter	Required	Accepted Values
lob	x	DNA, FIT, SC & CGX
order_number	x	order number used for original order
pwn_req_number		only required for SC

Auth required : YES

Response

Example Success Response

{
	"first_name": "Zano",
	"last_name": "Hsu",
	"address_1": "14401 SE 1st ST",
	"address_2": "Apt. B",
	"city": "Vancouver",
	"state": "WA",
	"postcode": "98684",
	"country": "USA",
	"phone": "",
	"email": "[email protected]",
	"gender": "Male",
	"date_of_birth": 1978-01-01
}

Example Failure Response

{
	"order_number": "999",
	"success": false,
	"error_msg": "Order number doesn't exist."
}

Register Kit

URL : /RegisterKit

Method : POST

Auth required : YES

Example Body

[
	{
	"lob": "SC",
	"kit_id": "F000000001",
	"patient_info":{
		"first_name": "John",
		"last_name": "Doe",
		"address_1": "14401 SE 1st ST",
		"address_2": "",
		"city": "Vancouver",
		"state": "WA",
		"postcode": "98684",
		"gender": "male",
		"date_of_birth": "1962-06-03",
		"email": "[email protected]",
		"phone": "123-842-9999"
	},
	"pwn_req_number": "5142800"
	}
]

• All fields are required, except email & phone, but either of email & phone needs to provide.
• pwn_req_number is optional and is for SC only

Responses

Example Success Response

[
	{
		"kit_id": "F000000001",
		"success": true,
		"error_msg": " null "
	}
]

Example Failure Response

[
	{
		"kit_id": "F000000001",
		"success": false,
		"error_msg": "gender is missing"
	}
]

Register Code

For a client to retrieve the registration code for the kit.

URL : /RegisterCode

Method : GET

URL Parameters :

Parameter	Required	Accepted Values
kit_id	x

Auth required : YES

Responses

Example Success Response

{
	"kit_id": " UA00000001",
	"register_code": "KO99YXoH",
	"success": true,
	"error_msg": null
}

Example Failure Response

{
	"kit_id": "UA00000001",
	"register_code": null,
	"success": false,
	"error_msg": "The kit id is not exist."
}

Appendix

FAQ

1. Are all endpoints capitalized when used in URL/Endpoint?

   URLs are not case sensitive, but parameters are.

2. What are the parameters for PlaceOrder endpoint? Would it be different when placing multiple orders?

   No parameters are needed for PlaceOrder, all info would be in the payload. There's no difference for placing an order and multi-orders.

3. In Notification endpoint, if we request all orders' information, how do we specify it's all orders of us?

   Each client has its own GUID, so when you place orders, we would know the orders are from which client, therefore, from the GUID & user(headers), we would know who is requesting for the info.

4. What is the data type of "order_number"?

   It’s a string data type, 20 char. length, it needs to be a unique id due to we use it to communicate with.

5. What is the 'Lob' parameter on the endpoints

   Lob stands for line of business, we would allow a client to place an order for SC, DNA, FIT, etc.

6. Since we are a distributor, so how is the physician_id supposed to work? There is mention in the document that this is the unique id of the physician within the MTL system.

   This physician_id is an account for you on MTL portal, and you can use this account for viewing all of orders, report, etc.,

   You can assume it as an account id in MTL portal when you are a distributor.

Changelog

• V1.2 add Lob: DNA + insurance +pwn_req_no
• V1.2.1 add FAQ
• V1.3 add DNA test raw result
• V1.3.1 test result ready list
• V1.4 add FIT
• V1.4.1 add new additional tests feature for SC
• V1.4.2 add replacement feature for SC & appendix
• V1.5 add CGX
• V1.5.1 add error list for placing orders, Add plan_code for FIT
• V1.5.2 allow client to update patient info.
• V1.5.3 allow client to retrieve patient info.
• V1.5.4 add “recoverable” status for rejected notification
• V1.5.5 add “kit_reg_code” status in kit shipped notification
• V1.5.6 add “pwn_req_number” in registration(update patient info.)
• V1.6 kit registration
• V1.7 push notification
• V1.8 get registration code
• V1.9 add ethnicity to patient
• V2.0 add ID LOB
• V2.01 add “result_value” & “assay_datetime” to test result
• V2.02 add “tempstrip_status” to test result for ID use