Create requisition

cURL

curl --request POST \
  --url https://app.spotdx.com/api/v2/requisitions/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "barcode": "19742938328",
  "panels": [
    "PANEL-123"
  ],
  "account_number": "1234567890",
  "lab": "CRL",
  "state_collected": "OH",
  "patient": {
    "first_name": "Alice",
    "last_name": "Smith",
    "email": "alice123@gmail.com",
    "phone": "1234567890",
    "sex": "F",
    "date_of_birth": "2023-12-25"
  },
  "tracking": {
    "tracking_number": "9400123456789999876500",
    "carrier": "usps"
  },
  "attributes": {
    "crl_slip_id": "1234567890"
  },
  "metadata": {
    "some_key": "some_value"
  }
}
'

import requests

url = "https://app.spotdx.com/api/v2/requisitions/"

payload = {
    "barcode": "19742938328",
    "panels": ["PANEL-123"],
    "account_number": "1234567890",
    "lab": "CRL",
    "state_collected": "OH",
    "patient": {
        "first_name": "Alice",
        "last_name": "Smith",
        "email": "alice123@gmail.com",
        "phone": "1234567890",
        "sex": "F",
        "date_of_birth": "2023-12-25"
    },
    "tracking": {
        "tracking_number": "9400123456789999876500",
        "carrier": "usps"
    },
    "attributes": { "crl_slip_id": "1234567890" },
    "metadata": { "some_key": "some_value" }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    barcode: '19742938328',
    panels: ['PANEL-123'],
    account_number: '1234567890',
    lab: 'CRL',
    state_collected: 'OH',
    patient: {
      first_name: 'Alice',
      last_name: 'Smith',
      email: 'alice123@gmail.com',
      phone: '1234567890',
      sex: 'F',
      date_of_birth: '2023-12-25'
    },
    tracking: {tracking_number: '9400123456789999876500', carrier: 'usps'},
    attributes: {crl_slip_id: '1234567890'},
    metadata: {some_key: 'some_value'}
  })
};

fetch('https://app.spotdx.com/api/v2/requisitions/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.spotdx.com/api/v2/requisitions/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'barcode' => '19742938328',
    'panels' => [
        'PANEL-123'
    ],
    'account_number' => '1234567890',
    'lab' => 'CRL',
    'state_collected' => 'OH',
    'patient' => [
        'first_name' => 'Alice',
        'last_name' => 'Smith',
        'email' => 'alice123@gmail.com',
        'phone' => '1234567890',
        'sex' => 'F',
        'date_of_birth' => '2023-12-25'
    ],
    'tracking' => [
        'tracking_number' => '9400123456789999876500',
        'carrier' => 'usps'
    ],
    'attributes' => [
        'crl_slip_id' => '1234567890'
    ],
    'metadata' => [
        'some_key' => 'some_value'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.spotdx.com/api/v2/requisitions/"

	payload := strings.NewReader("{\n  \"barcode\": \"19742938328\",\n  \"panels\": [\n    \"PANEL-123\"\n  ],\n  \"account_number\": \"1234567890\",\n  \"lab\": \"CRL\",\n  \"state_collected\": \"OH\",\n  \"patient\": {\n    \"first_name\": \"Alice\",\n    \"last_name\": \"Smith\",\n    \"email\": \"alice123@gmail.com\",\n    \"phone\": \"1234567890\",\n    \"sex\": \"F\",\n    \"date_of_birth\": \"2023-12-25\"\n  },\n  \"tracking\": {\n    \"tracking_number\": \"9400123456789999876500\",\n    \"carrier\": \"usps\"\n  },\n  \"attributes\": {\n    \"crl_slip_id\": \"1234567890\"\n  },\n  \"metadata\": {\n    \"some_key\": \"some_value\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.spotdx.com/api/v2/requisitions/")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"barcode\": \"19742938328\",\n  \"panels\": [\n    \"PANEL-123\"\n  ],\n  \"account_number\": \"1234567890\",\n  \"lab\": \"CRL\",\n  \"state_collected\": \"OH\",\n  \"patient\": {\n    \"first_name\": \"Alice\",\n    \"last_name\": \"Smith\",\n    \"email\": \"alice123@gmail.com\",\n    \"phone\": \"1234567890\",\n    \"sex\": \"F\",\n    \"date_of_birth\": \"2023-12-25\"\n  },\n  \"tracking\": {\n    \"tracking_number\": \"9400123456789999876500\",\n    \"carrier\": \"usps\"\n  },\n  \"attributes\": {\n    \"crl_slip_id\": \"1234567890\"\n  },\n  \"metadata\": {\n    \"some_key\": \"some_value\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.spotdx.com/api/v2/requisitions/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"barcode\": \"19742938328\",\n  \"panels\": [\n    \"PANEL-123\"\n  ],\n  \"account_number\": \"1234567890\",\n  \"lab\": \"CRL\",\n  \"state_collected\": \"OH\",\n  \"patient\": {\n    \"first_name\": \"Alice\",\n    \"last_name\": \"Smith\",\n    \"email\": \"alice123@gmail.com\",\n    \"phone\": \"1234567890\",\n    \"sex\": \"F\",\n    \"date_of_birth\": \"2023-12-25\"\n  },\n  \"tracking\": {\n    \"tracking_number\": \"9400123456789999876500\",\n    \"carrier\": \"usps\"\n  },\n  \"attributes\": {\n    \"crl_slip_id\": \"1234567890\"\n  },\n  \"metadata\": {\n    \"some_key\": \"some_value\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "requisition_id": "f0e5a607-5b52-4d7c-a3f2-c40772d41482",
  "barcode": "19742938328",
  "account_number": "1234567890",
  "panels": ["PANEL-123"],
  "state_collected": "OH",
  "patient": {
    "first_name": "Alice",
    "last_name": "Smith",
    "email": "alice123@gmail.com",
    "phone": "1234567890",
    "sex": "F",
    "date_of_birth": "2023-02-01",
    "address": {
      "street1": "123 Main St",
      "street2": "Apt 1",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "zip": "94105"
    }
  },
  "tracking": {
    "tracking_number": "9400123456789999876500",
    "carrier": "usps"
  },
  "status": "approved",
  "events": [
    {
      "event": "created",
      "date": "2020-01-01T00:00:00Z"
    },
    {
      "event": "approved",
      "date": "2020-01-01T00:00:00Z"
    }
  ],
  "reports": [],
  "metadata": null
}

POST

api

requisitions

cURL

curl --request POST \
  --url https://app.spotdx.com/api/v2/requisitions/ \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "barcode": "19742938328",
  "panels": [
    "PANEL-123"
  ],
  "account_number": "1234567890",
  "lab": "CRL",
  "state_collected": "OH",
  "patient": {
    "first_name": "Alice",
    "last_name": "Smith",
    "email": "alice123@gmail.com",
    "phone": "1234567890",
    "sex": "F",
    "date_of_birth": "2023-12-25"
  },
  "tracking": {
    "tracking_number": "9400123456789999876500",
    "carrier": "usps"
  },
  "attributes": {
    "crl_slip_id": "1234567890"
  },
  "metadata": {
    "some_key": "some_value"
  }
}
'

import requests

url = "https://app.spotdx.com/api/v2/requisitions/"

payload = {
    "barcode": "19742938328",
    "panels": ["PANEL-123"],
    "account_number": "1234567890",
    "lab": "CRL",
    "state_collected": "OH",
    "patient": {
        "first_name": "Alice",
        "last_name": "Smith",
        "email": "alice123@gmail.com",
        "phone": "1234567890",
        "sex": "F",
        "date_of_birth": "2023-12-25"
    },
    "tracking": {
        "tracking_number": "9400123456789999876500",
        "carrier": "usps"
    },
    "attributes": { "crl_slip_id": "1234567890" },
    "metadata": { "some_key": "some_value" }
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    barcode: '19742938328',
    panels: ['PANEL-123'],
    account_number: '1234567890',
    lab: 'CRL',
    state_collected: 'OH',
    patient: {
      first_name: 'Alice',
      last_name: 'Smith',
      email: 'alice123@gmail.com',
      phone: '1234567890',
      sex: 'F',
      date_of_birth: '2023-12-25'
    },
    tracking: {tracking_number: '9400123456789999876500', carrier: 'usps'},
    attributes: {crl_slip_id: '1234567890'},
    metadata: {some_key: 'some_value'}
  })
};

fetch('https://app.spotdx.com/api/v2/requisitions/', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.spotdx.com/api/v2/requisitions/",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'barcode' => '19742938328',
    'panels' => [
        'PANEL-123'
    ],
    'account_number' => '1234567890',
    'lab' => 'CRL',
    'state_collected' => 'OH',
    'patient' => [
        'first_name' => 'Alice',
        'last_name' => 'Smith',
        'email' => 'alice123@gmail.com',
        'phone' => '1234567890',
        'sex' => 'F',
        'date_of_birth' => '2023-12-25'
    ],
    'tracking' => [
        'tracking_number' => '9400123456789999876500',
        'carrier' => 'usps'
    ],
    'attributes' => [
        'crl_slip_id' => '1234567890'
    ],
    'metadata' => [
        'some_key' => 'some_value'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://app.spotdx.com/api/v2/requisitions/"

	payload := strings.NewReader("{\n  \"barcode\": \"19742938328\",\n  \"panels\": [\n    \"PANEL-123\"\n  ],\n  \"account_number\": \"1234567890\",\n  \"lab\": \"CRL\",\n  \"state_collected\": \"OH\",\n  \"patient\": {\n    \"first_name\": \"Alice\",\n    \"last_name\": \"Smith\",\n    \"email\": \"alice123@gmail.com\",\n    \"phone\": \"1234567890\",\n    \"sex\": \"F\",\n    \"date_of_birth\": \"2023-12-25\"\n  },\n  \"tracking\": {\n    \"tracking_number\": \"9400123456789999876500\",\n    \"carrier\": \"usps\"\n  },\n  \"attributes\": {\n    \"crl_slip_id\": \"1234567890\"\n  },\n  \"metadata\": {\n    \"some_key\": \"some_value\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://app.spotdx.com/api/v2/requisitions/")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"barcode\": \"19742938328\",\n  \"panels\": [\n    \"PANEL-123\"\n  ],\n  \"account_number\": \"1234567890\",\n  \"lab\": \"CRL\",\n  \"state_collected\": \"OH\",\n  \"patient\": {\n    \"first_name\": \"Alice\",\n    \"last_name\": \"Smith\",\n    \"email\": \"alice123@gmail.com\",\n    \"phone\": \"1234567890\",\n    \"sex\": \"F\",\n    \"date_of_birth\": \"2023-12-25\"\n  },\n  \"tracking\": {\n    \"tracking_number\": \"9400123456789999876500\",\n    \"carrier\": \"usps\"\n  },\n  \"attributes\": {\n    \"crl_slip_id\": \"1234567890\"\n  },\n  \"metadata\": {\n    \"some_key\": \"some_value\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://app.spotdx.com/api/v2/requisitions/")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"barcode\": \"19742938328\",\n  \"panels\": [\n    \"PANEL-123\"\n  ],\n  \"account_number\": \"1234567890\",\n  \"lab\": \"CRL\",\n  \"state_collected\": \"OH\",\n  \"patient\": {\n    \"first_name\": \"Alice\",\n    \"last_name\": \"Smith\",\n    \"email\": \"alice123@gmail.com\",\n    \"phone\": \"1234567890\",\n    \"sex\": \"F\",\n    \"date_of_birth\": \"2023-12-25\"\n  },\n  \"tracking\": {\n    \"tracking_number\": \"9400123456789999876500\",\n    \"carrier\": \"usps\"\n  },\n  \"attributes\": {\n    \"crl_slip_id\": \"1234567890\"\n  },\n  \"metadata\": {\n    \"some_key\": \"some_value\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "requisition_id": "f0e5a607-5b52-4d7c-a3f2-c40772d41482",
  "barcode": "19742938328",
  "account_number": "1234567890",
  "panels": ["PANEL-123"],
  "state_collected": "OH",
  "patient": {
    "first_name": "Alice",
    "last_name": "Smith",
    "email": "alice123@gmail.com",
    "phone": "1234567890",
    "sex": "F",
    "date_of_birth": "2023-02-01",
    "address": {
      "street1": "123 Main St",
      "street2": "Apt 1",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "zip": "94105"
    }
  },
  "tracking": {
    "tracking_number": "9400123456789999876500",
    "carrier": "usps"
  },
  "status": "approved",
  "events": [
    {
      "event": "created",
      "date": "2020-01-01T00:00:00Z"
    },
    {
      "event": "approved",
      "date": "2020-01-01T00:00:00Z"
    }
  ],
  "reports": [],
  "metadata": null
}

Access to requisitioning is disabled by default. To enable it, talk to us and we’ll get you set up

After creating a new requisition, we will immediately respond with an approved or denied status code.

{
  "requisition_id": "f0e5a607-5b52-4d7c-a3f2-c40772d41482",
  "barcode": "19742938328",
  "account_number": "1234567890",
  "panels": ["PANEL-123"],
  "state_collected": "OH",
  "patient": {
    "first_name": "Alice",
    "last_name": "Smith",
    "email": "alice123@gmail.com",
    "phone": "1234567890",
    "sex": "F",
    "date_of_birth": "2023-02-01",
    "address": {
      "street1": "123 Main St",
      "street2": "Apt 1",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "zip": "94105"
    }
  },
  "tracking": {
    "tracking_number": "9400123456789999876500",
    "carrier": "usps"
  },
  "status": "approved",
  "events": [
    {
      "event": "created",
      "date": "2020-01-01T00:00:00Z"
    },
    {
      "event": "approved",
      "date": "2020-01-01T00:00:00Z"
    }
  ],
  "reports": [],
  "metadata": null
}

Authorizations

Authorization

string

header

required

Token-based authentication with required prefix "Token"

Body

application/json

barcode

string

required

The barcode of the sample mailed to the lab. We use this to identify the sample from the lab report.

Example:

"19742938328"

panels

string[]

required

The panel codes of the test being performed on the sample. We'll create these with you during onboarding.

Example:

["PANEL-123"]

account_number

string

required

The account number submitted to the lab.

Example:

"1234567890"

lab

string

required

The name of the lab that will process the sample.

Example:

"CRL"

state_collected

string

required

The two letter code of the state where the sample was collected.

Example:

"OH"

patient

object

required

Show child attributes

tracking

object

Show child attributes

Example:

{
  "tracking_number": "9400123456789999876500",
  "carrier": "usps"
}

attributes

object | null

An optional set of values that can be passed through to specific labs.

Show child attributes

Example:

{ "crl_slip_id": "1234567890" }

metadata

object | null

An optional dictionary of key-value pairs stored with the requisition.

Example:

{ "some_key": "some_value" }

Response

requisition_id

string

The ID of the requisition.

Example:

"f0e5a607-5b52-4d7c-a3f2-c40772d41482"

barcode

string

The full barcode of the sample mailed to the lab. Must be globally unique.

Example:

"19742938328"

account_number

string

The account number submitted to the lab.

Example:

"1234567890"

lab

string

The name of the lab that will process the sample.

Example:

"CRL"

panels

string[]

The panel codes of the test being performed on the sample. We'll create these with you during onboarding.

Example:

["PANEL-123"]

state_collected

string

The two letter code of the state where the sample was collected.

Example:

"OH"

patient

object

Show child attributes

tracking

object

Show child attributes

status

enum<string>

Available options:

created,

approved,

denied,

delivered,

received,

extra_quality_checks,

resulted,

rejected,

delivery_exception

Example:

"resulted"

events

object[]

Show child attributes

Example:

[
  {
    "event": "created",
    "date": "2020-01-01T00:00:00Z"
  },
  {
    "event": "approved",
    "date": "2020-01-01T00:00:00Z"
  },
  {
    "event": "delivered",
    "date": "2020-01-02T00:00:00Z"
  },
  {
    "event": "received",
    "date": "2020-01-03T00:00:00Z"
  },
  {
    "event": "extra_quality_checks",
    "date": "2020-01-04T00:00:00Z"
  },
  {
    "event": "resulted",
    "date": "2020-01-05T00:00:00Z"
  }
]

reports

(object | null)[]

Show child attributes

attributes

object | null

An optional set of values that can be passed through to specific labs.

Show child attributes

Example:

{
  "crl_slip_id": "1234567890",
  "crl_tier3_account_number": "12345678"
}

metadata

object | null

An optional dictionary of key-value pairs stored with the requisition.

Example:

{ "some_key": "some_value" }

created

string<date-time>

Example:

"2020-01-01T00:00:00Z"

updated

string<date-time>

Example:

"2020-01-01T00:00:00Z"

Get kit by ID List requisitions

⌘I

Welcome

Basic Guides

Advanced Guides

Integrations

API Reference - Orders

API Reference - Kits

API Reference - Requisitions

API Reference - Registration

Create requisition

Authorizations

Body

Response