API Documentation

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

[Last updated on September 1, 2021]

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": "zano@test.com", 
	"phone": "123-842-9999", 
	"shipping_method": 7, 
	"panel_id": [ 26,27 ], 
	"physician_id": 1234, 
	"lob": "SC", 
	"fulfillment": true, 
	"kit_id": null, 
	"patient_signature": null, 
	"p_ethnicity_id": 1, 
	"p_race_id": 3, 
	"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": "",
		"secondary_payer": "",
		"secondary_member_id": "",
		"secondary_group_number": "",
		"secondary_claims_address": "",
		"secondary_first_name": "",
		"secondary_last_name": "",
		"secondary_dob": "",
		"secondary_insured_relationship": "",
		"secondary_address_1": "",
		"secondary_address_2": "",
		"secondary_city": "",
		"secondary_state": "",
		"secondary_zip": ""
	}, 
	"pwn_req_number":"", 
	"replacement": { 
		"origin_order_number": null 
	}, 
	"patient_id": "", 
	"custom_field": { 
		"custom_01":"custom filed info." 
	}
}]

When making a large number of API calls all at once, please insert a 500-millisecond delay between requests.

Object Notes

Variable	Expected Type	Length	Notes
order_number	string	20	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)
panel_id	int array		panels to be ordered - see Example Panel Codes
gender	string		this is sex at birth and should be entered as either 'male', 'female', or 'unknown'
lob	string		line of business: SC - Self Collect DNA FIT - Fitness CGx - Cancer Genomics ID - Infectious Disease
shipping_method	number		7 – USPS Priority Non-Flat Rate (1-3 Days) **Default value if invalid or null value passed 8 – USPS Express (Overnight) 9 – USPS First Class (2-5 Days) 10 – FedEx Priority Overnight (Saturday Delivery) 12 – FedEx Standard Overnight (Non-Saturday Delivery) 13 – USPS Priority Flat Rate (1-3 Days) 16 – FedEx Express Saver (3 Days) Shipping method is based on contractual agreement**
fulfillment	boolean		must be set to true if Molecular needs to ship a kit
kit_id	string	10	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)
p_ethnicity_id	number		1 - Hispanic or Latino 2 - Not Hispanic or Latino
p_race_id	number		1 - American Indian or Alaska Native 2 - Asian 3 - Black or African American 4 - Native Hawaiian or Other Pacific Islander 5 - White/Caucasian 6 - Other
is_primary_insured	boolean		discontinued field; should be left blank or null
primary_gender	boolean		discontinued field; should be left blank or null
primary_first_name	string		must be alphabetic characters only
primary_last_name	string		must be alphabetic characters only
primary_relationship	string		must be 'Child', 'Spouse', 'Self', or 'Other'
secondary_first_name	string		must be alphabetic characters only
secondary_last_name	string		must be alphabetic characters only
secondary_insured_relationship	string		must be 'Child', 'Spouse', 'Self', or 'Other'
pwn_req_number	string	20	for SC use, MTL sends a copy of test result to PWN when the field has a value
origin_order_number	string		for SC use, only charges for kit/fulfill/shipping when creating an order for a replacement kit
plan_code	string		for BCBSA use
patient_id	string	30	clinic patient id, for linking patient's orders together, this id must be unique for each patient in order to prevent overwriting other patient data
custom_01	string	255	SC only. Clinic can use it to store their custom info. and retrieve from the endpoint of OrderInfo

Example Panel Codes

LOB	Panel ID	Panel List
SC	26	Gonorrhea
SC	27	Chlamydia
SC	56	Hep B (DBS), Creatinine (DBS), HIV
SC	84	Creatinine (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	yyyy-mm-dd
panel_id
physician_id
lob
kit_id	required when 'fulfillment' = 'false', is left empty, null, or not passed
patient_signature	required when a client fulfill DNA kit by themselves
ordered_date	YYYY-MM-DD HH:MM:SS (UTC)
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." 
}

Error Messages for /PlaceOrder

Invalid LOB.
Order number is required.
Test ordered is required.
Patient name is required.
Address is required.
Gender is required.
Physician is not registered in the practice.
Duplicated kit id.
Duplicated order number.
Invalid physician id.
Missing/Invalid test code.
Errors when creating patient demographic.
State has wrong format, please use state code, ex: WA for Washington
Zip code has wrong format, ex: 98684
Primary first name has digits, please enter valid information
Primary first name has special characters, please enter valid information
Primary last name has digits, please enter valid information
Primary last name has special characters, please enter valid information
Primary relationship has invalid entry, please enter relationship like ex: Child, Spouse, Self, Other
Secondary first name has digits, please enter valid information
Secondary first name has special characters, please enter valid information
Secondary last name has digits, please enter valid information
Secondary last name has special characters, please enter valid information
Secondary relationship has invalid entry, please enter relationship like ex: Child, Spouse, Self, Other
kit_id must be empty/null if fulfillment = true
kit_id is required if fulfillment = false
"The process cannot access the file \'C:\\\\inetpub\\\\wwwroot\\\\MTL_LIS_API\\\\data\\\\...' because it is being used by another process."'

This error can sometimes occur when making a large amount of API calls at a time. Please insert a 500-millisecond delay between each call.

[Last updated on July 31, 2023]

Retrieve Lab Order Info

For a client to retrieve the order info. for the kit.

URL:

/OrderInfo

URL Parameters:

Parameter	Required	Accepted Values
lob	x	SC - only support SC right now
order_number	x	order number used when placing an order

Method:

GET

Auth Required:

YES

Responses

Example Response

{ 
	"order_number": "0015", 
	"kit_id": "CV00001234", 
	"panel_id": [ 154 ], 
	"test_ordered": "COVID-19 Anterior-Nares", 
	"sample_collect_date": "2020-10-11T07:00:00.000Z", 
	"sample_received_date": "2020-10-12T07:00:00.000Z", 
	"patient_info": { 
		"first_name": "John", 
		"last_name": "Doe",
		"address_1": "123 Big Road", 
		"address_2": "", 
		"city": "Vancouver", 
		"state": "WA", 
		"postcode": "98684", 
		"country": "USA", 
		"phone": "123-842-9999", 
		"email": "zano@test.com", 
		"gender": "Male", 
		"date_of_birth": "1962-06-03", 
		"p_ethnicity_id": 1, 
		"p_race_id": 3 
	}, 
	"custom_field": { 
		"custom_01": "custom filed info." 
	}
}

Patient Ethnicity and Race

Ethnicity Example Codes

ID	Name
1	Hispanic or Latino
2	Not Hispanic or Latino

Race Example Codes

ID	Name
1	American Indian or Alaska Native
2	Asian
3	Black or African American
4	Native Hawaiian or Other Pacific Islander
5	White/Caucasian
6	Other

[Last updated on June 30, 2023]

Delete Lab 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 back at the lab - charge kit & fulfillment fee
After receiving back to lab - the order cannot be cancelled after it is processed

[Last updated on November 1, 2021]

Retrieve Lab Order 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 are in the report ready status for the 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", 
	"tempstrip_status": "", 
	"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", 
	"tempstrip_status": "", 
	"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", 
	"tempstrip_status": "", 
	"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" }]
}

[Last updated on November 1, 2021]

Update Test Ordered

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, Molecular will reply status for each order.

Success

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

Example Success Response

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

If Molecular 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 
}]

[Last updated on December 2, 2022]

Check the Status of "waiting for approval" Orders

URL:

/AddNewTest

URL Parameters:

Parameter	Required	Accepted Values
lob	x	SC

Method:

GET

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
}]

[Last updated on December 2, 2022]

Retrieve Kit Info

Check order status

URL:

/Notification

URL Parameters:

Parameter	Required	Accepted Values
lob	x	SC, ID, DNA, FIT, CGx
type	x	kit_shipped, kit_received, kit_rejected
order_number	x	check an order_number or an array of order_number(s) with a specific type to see if they are in the specified type. If an order_number(s) is not specified for a specific type, then all order_numbers within that type will be 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": "Quantity Not Sufficient",
		"recoverable": false 
	} 
}]

"recoverable" can be null when the rejection is not defined as recoverable or not. For a list of rejection reasons, navigate to Notifications -> Webhooks

[Last updated on July 19, 2023]

Delete Kit info

Remove Orders from Notification List

URL:

/Notification

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

[Last updated on November 1, 2021]

Bulk Kit Tracking

For a client to retrieve inbound shipping information from bulk shipped kits

URL:

/KitTracking

URL Parameters:

Parameter	Required	Accepted Values
kit_id	x

Method:

GET

Auth Required:

YES

Example Success Response

{ 
	"kit_id": "MTL0123456",
	"inbound": "9999999999999999999999"
}

Example Failure Response

{
    "error_msg": "invalid kit_id."
}

The list of "error_msg" for placing an order:

Invalid kit_id

[Last updated on December 29, 2022]

Retrieve Patient Info

URL:

/Patient

URL Parameters:

Parameter	Required	Accepted Values
lob	x	DNA, FIT, SC, CGX
order_number	x	order number used for original order
pwn_req_number		pwn_req_number is only available for SC for applicable clients

Method:

GET

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": "zano@yahoo.com", 
	"gender": "Male", 
	"date_of_birth": "1978-01-01", 
	"p_ethnicity_id": 1, 
	"p_race_id": 3 
}

Example Failure Response

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

Patient Ethnicity and Race

Ethnicity Example Codes

ID	Name
1	Hispanic or Latino
2	Not Hispanic or Latino

Race Example Codes

ID	Name
1	American Indian or Alaska Native
2	Asian
3	Black or African American
4	Native Hawaiian or Other Pacific Islander
5	White/Caucasian
6	Other

[Last updated on June 30, 2023]

Update patient Info

Interact with Patient Object

URL:

/Patient

URL Parameters:

Parameter	Required	Accepted Values
lob	x	DNA, FIT, SC, CGX
pwn_req_number		pwn_req_number is only available for SC for applicable clients

Method:

PUT

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": "zano@test.com", 
		"phone": "123-842-9999", 
		"p_ethnicity_id": 2, 
		"p_race_id": 4 
	}, 
	"order_number": "0200001", 
	"lob": "CGX"
}

Response

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

Patient Ethnicity and Race

Ethnicity Example Codes

ID	Name
1	Hispanic or Latino
2	Not Hispanic or Latino

Race Example Codes

ID	Name
1	American Indian or Alaska Native
2	Asian
3	Black or African American
4	Native Hawaiian or Other Pacific Islander
6	Other

[Last updated on June 30, 2023]

Create Kit Registration

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": "zano@test.com", 
		"phone": "123-842-9999", 
		"p_ehtnicity_id": 2, 
		"p_race_id": 4 
	}, 
	"pwn_req_number": "5142800" 
}]

All fields are required, except email & phone, but either email or phone needs to be provided. Both p_ethinicity_id and p_race_id are also not required fields.
pwn_req_number is optional and is for SC only

Patient Ethnicity and Race

Ethnicity Example Codes

ID	Name
1	Hispanic or Latino
2	Not Hispanic or Latino

Race Example Codes

ID	Name
1	American Indian or Alaska Native
2	Asian
3	Black or African American
4	Native Hawaiian or Other Pacific Islander
5	White/Caucasian
6	Other

Reponses

Example Success Reponse

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

Example Failure Response

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

[Last updated on June 29, 2023]

Read Registration Code

For a client to retrieve the registration code for the kit

URL:

/RegisterCode

URL Parameters:

Parameter	Required	Accepted Values
kit_id	x

Method:

GET

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."
}

[Last updated on November 1, 2021]

Webhooks

Subscribe to receive push notifications with Kit of Lab Order status

URL:

define by client

Method:

POST

Auth Required:

A client needs to provide an endpoint(url) for Molecular to set up where to send to notification to, the endpoint can use basic authentication for the request, Username & Password would be the user & token that are provided by Molecular(same user & token in Authentication).

Content Type: application/json

Object Notes

Variable	Expected Type	Notes
order_number	string
accession_number	string
type	string	notification type
outbound	string	outbound USPS/FedEx tracking number
inbound	string	return USPS/FedEx tracking number
shipped_datetime	string
kit_reg_code	string
oraquick_lot_exp	string	for OraQuick kit use
received_datetime	string
rejected_datetime	string
rejected_reason	string
recoverable	boolean	can be placed back to production or not
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, 
		"oraquick_lot_exp": "" 
	}, 
	"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-01-11T19:53:08.885569Z" 
	}, 
	"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-01-11T19:53:08.885569Z", 
		"rejected_reason": "No patient identifiers listed on the sample 
		 container / envelope.", 
		"recoverable": false 
	}, 
	"report_ready_info": null 
}

Rejection Reasons (SC only)

Rejection Reason	Can be placed back into Production?
Quantity Not Sufficient	No
Invalid specimen type / collection device	No
No patient identifiers listed on the sample container / envelope.	No
NY State Sample. Not Yet CLIA certified.	No
Specimen damaged during shipment, unable to test specimen.	No
Cross-Contamination: Sample spill resulting in possible contamination of multiple specimens.	No
Patient identifier mix up	Yes
No Specimen Provided	No
Individual specimen leak, quantity insufficient for testing.	No
Missing one (1) patient identifier on the sample container or envelope.	Yes
Unknown Collection Site	No
Rejected per Distributor/Patient Request.	Yes
Expired Device	No
Gender/Kit Discrepancy	Yes
Specimen Over-filled	No
Minor. Guardian Signature Not Provided	Yes
Collection date exceeds 30 days	No
Collection Date Exceeds Acceptance Criteria.	No
Kit Not Used	No
Return to Sender	No
Sample integrity compromised	No
Unregistered Kit	Yes

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-01-11T19:53:08.885569Z" 
	} 
}

[Last updated on July 19, 2023]

FAQ

Are all endpoints capitalized when used in URL/Endpoint?

URLs are not case sensitive, but parameters are.

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.

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.

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.

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.

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.

[Last updated on August 31, 2021]

Send us a message

How can we help?

We usually respond in a few hours

Address: 14401 SE 1st Street, Vancouver, WA 98684