API Walkthrough

To communicate with the Molecular Testing Labs (“ Molecular”) API, you’ll need to obtain a user_id and token from our engineering team. Any request must include those values in the headers for authentication purposes.

When reading our API documentation, not that this is an RPC API, and you’ll largely be performing actions based on your “ order_number”.

Getting Started

Placing a Diagnostic Order

When you create a new account, there won’t be any information to interact with, so the best place to start is POSTing to the /PlaceOrder endpoint.

NOTE: We require all diagnostic orders to have an overseeing provider registered in the state where samples are collected. When placing an order via the API, we require a unique physician_id generated by us. If you do not have at least one physician_id, please reach out to our registration department.

When placing an order, we are expecting a non-empty array of orders. A sample order can be seen below, but first, let us explain a couple terms.

Variable Terms

order_number – this is a string (generated by you) that can be up to 20 characters. It will be the primary identifier that you use to communicate with our API. You cannot reuse order_numbers for the same user token, so make sure to have a non-duplicative process for generating them.

kit_id – throughout our systems this can also be referred to as the accessioning_id, or the tracking_id. It must be used as the barcode on all collection devices in each order. We track samples across machines and labs using this kit_id number.

This identifier can also be used when communicating with our customer support team without exchanging any PHI.

  • If we are fulfilling kits on your behalf, we will generate this for you. It will be returned in the response to a successful POST.
  • If you are fulfilling kits, please note that this id must be 10 characters or less. It should also be unique for every order placed with a user token.

lob – this stands for “Line of Business”. Except in very rare circumstances, you should be using the string “SC” for self-collect. Please speak with your account representative if you believe otherwise.

panel_id – this is an array of integers identifying the diagnostics you’d like run on the patient.

Your account representative will provide you with a detailed list of panel_ids and corresponding prices.

fulfillment – if you’ve signed an agreement for Molecular to provide packaging and shipping of medical devices to patients for self-collection, then you will need to use this field with a

shipping_method – if fulfillment is set to true, you must also include the shipping speed to and from the patient. Your options are stated below:

  • 7 – USPS Priority – 1-3 days nationwide - $8.60 each way
  • 8 – USPS Express – 1-2 days nationwide – [fill in one way price]
  • 9 – USPS First Class – 3-5 days nationwide - $4.00 each way
  • 10 – FedEx Overnight - $24.00 each way

patient_id – if you’d like to assign an identifier to a patient to match data with your own system, this is an optional field. It must be unique and can be up to 30 characters.

gender – this is a string expecting a binary response of “male” or “female” to denote the patient’s sex at birth.

shipping_info – we require shipping info even if we are not sending the patient a kit. This is used for mandatory reporting to state health departments.

If we are shipping a kit to your patient and their primary residence is different than their shipping address, you can update the patient’s address after the kit has been delivered to them using the PUT /Patient endpoint.

Example Order

Let's say you've got a patient—Ms Molly Cular—that needs diagnostic testing to continue prescribing her an HIV prevention medication. Her provider wants testing for HIV antibodies/antigens, Syphilis antibodies, Creatinine, and multi-site Chlamydia and Gonorrhea.

Method: POST

URL: /PlaceOrder

Auth required: YES

Panels IDs: 

  • HIV Ab/Ag - 11
  • Syphilis Ab - 12
  • Creatinine - 46
  • Pharyngeal CT/GC - 99
  • Genital CT/GC - 194
  • Rectal CT/GC - 189
Example Headers:
	"Content-Type": "application/json",
	"user": process.env.MTL_API_USER,
	"token": process.env.MTL_API_TOKEN
Example Body:
	"order_number": "123123",
	"ordered_date": "2018-07-09T19:53:08.885569Z ",
	"physician_id": 61745,
	"panel_id": [11, 12, 46, 99, 194, 189],
	"patient_id": null,
	"gender": "female",
	"date_of_birth": "1962-06-03",
	"email": "hello@moleculartestinglabs.com",
	"phone": "360-693-8850",
	"shipping_info": {
		"first_name": "Molly",
		"last_name": "Cular",
		"address_1": "14401 SE 1st Street",
		"address_2": "",
		"city": "Vancouver",
		"state": "WA",
		"postcode": "98684",
		"country": "USA"
	"lob": "SC",
	"fulfillment": true,
	"shipping_method": 7,
	"kit_id": null,
Example Responses

Example Success Response

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

Example Failure Response

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

Getting Order Updates

Still need help? Contact Us Contact Us