Order creation

Introduction

If you haven't already, sign up for a free sandbox account. You can then generate your API key from Developers > Api Keys. You will need this to authenticate most API calls. You will need to switch this key to a production one once you're ready to go live.

Read the Basic Test Flow to understand the lifecycle of a test.

Create an order

First, you need to know which product you want to order. You can get the list of products from the List Products API endpoint (you need the productCode) or from your account manager. Alternatively use C1BLP10300 as a starter (which is a general wellness at home test). In sandbox mode, no actual products will be shipped, but in production mode this endpoint requires a valid payment method and will ship the test.

📘

Product Codes

These will not change between the sandbox and production environment so you can hardcode these into your integration if you are focusing on specific products.

Once you have a product code, it's time to make your first API call to place an order. Remember to replace API_TOKEN with the one you generated earlier. For the full details see Create an order API endpoint.

const API_TOKEN = '<REPLACE_API_TOKEN_HERE>';

const options = {
  method: 'POST',
  headers: {
    'X-API-Key': API_TOKEN,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "productCode": "C1BLP10300",
    "quantity": 1,
    "delivery": {
      "address": {
        "addressLine1": "130 Plumstead Road",
        "addressLine2": "Plumstead",
        "city": "London",
        "postcode": "SE18 7DW",
        "countryCode": "GB"
      },
      "firstName": "Bob",
      "lastName": "Jones",
      "email": "[email protected]",
      "mobileNumber": "447789123456"
    },
  })
};

fetch('https://api.sandbox.hurdle.bio/orders/v3', options)
.then((res) => res.json())
.then((data) => {
  console.log("Response data:", data);
})
.catch((err) => {
  console.log("Unable to fetch:", err);
});

💾

Required fields

The required fields differ depending on the test type (at home/in-clinic etc). See Create an order for more details.

🚧

For US customers

You will need to set 'deliveryCountry' to 'US' and replace the deliveryCounty field by a deliveryState one. In addition, if your organization has physicians who are prescribing the order, you should add an extra physicianDetails object. Here is a snippet to replace the body creation part in the previous example:

const API_TOKEN = '<REPLACE_API_TOKEN_HERE>';

const options = {
  method: 'POST',
  headers: {
    'X-API-Key': API_TOKEN,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "productCode": "C1BLP10300",
    "quantity": 1,
    "delivery": {
      "address": {
        "addressLine1": "5 Newham Street",
        "addressLine2": "",
        "city": "San Francisco",
        "postcode": "94133",
        "deliveryState": "CA",
        "countryCode": "US"
      },
      "firstName": "Bob",
      "lastName": "Jones",
      "email": "[email protected]",
      "mobileNumber": "143454354534",
    },
    "physician": {
      "physicianId": "1234"
    }
  })
};

fetch('https://api.sandbox.hurdle.bio/orders/v3', options)
.then((res) => res.json())
.then((data) => {
  console.log("Response data:", data);
})
.catch((err) => {
  console.log("Unable to fetch:", err);
});

If you have added a credit card to your account and we could successfully charge it, or you have a commercial agreement the status will be "CONFIRMED" and the product will ship straight away.

Otherwise the status will be "CREATED" and the order will be in a pending state until payment is made. (See Orders > Order History page in dashboard)

Next steps

At this point, the test will ship to the customer and they are required to register it before returning it back to the lab. If you are using the Hurdle portal to do this, no further work is required (unless you want to add some white-label customisation). However if you wish to build the registration flow into your own app see the Linking user accounts guide for how to do this.