Authentication
All requests need the following options in Header:
| 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' | |
| date_of_birth | string | yyy-mm-dd | |
| lob | string | line of business:
|
|
| shipping_method | number |
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 |
|
|
| p_race_id | number |
|
|
| 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 | 297 | Flu |
Required Fields
| Variable | Notes | |
|---|---|---|
| order_number | ||
| phone | ||
| gender | ||
| 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.
- Invalid order number.
- 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 March 18, 2024]
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" ]
Omit the order_number parameter to list all order_number for orders that are in the report ready status for the last 7 days.
Retrieve Test Result Details
?lob="SC"&order_number="1234"
Responses
current_status– includes “not received yet”, “in process”, “rejected”, “cancelled”, “report ready” & null
Example Failure Response
{
"order_number": "1234",
"success": false,
"error_msg": null,
"current_status": "in process"
}Error Messages for /TestResult
- Invalid LOB
- Invalid order number
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 March 18, 2024]
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 with a specific type to see if it is in the specified type. If an order_number 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.
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
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.
[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:
NO
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 | |
| tracking_number | string | |
| label_type | string | "outbound" or "return" |
| shipping_status | string | |
| track_summary | 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
}USPS shipment tracking notification example
Clients need to “subscribe” to enable this feature. If interested please reach out to the integration specialist during onboarding or your client relation representative.
{
"order_number": "1010",
"accession_number": "M000145791",
"type": "USPS_shipment_tracking",
"ship_info": null,
"rcvd_info": null,
"rej_info": null,
"report_ready_info": null
"usps_info": {
"tracking_number": "9205590307774201758054",
"label_type": "outbound",
"shipping_status": "Delivered",
"track_summary": "Your item was delivered in or at the mailbox at 1:16 pm on August 9, 2023 in GAINESVILLE, FL 32608."
}
}For more information on the shipping_status, please visit Product Tracking and Reporting (PTR) | PostalPro (usps.com).
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 | No | |
| 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 February 7, 2024]
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
© 2023 Molecular Testing Labs. All Rights Reserved. CLIA #50D2050397 CAP #8690528