API Reference

Base URL:

Test: https://api.stage.chronomics.com/v1/
Production: https://api.chronomics.com/v1/

The Chronomics bio data API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the API in our test enviornment which will not affect your live data. The API key and URL you use to authenticate the request determines whether the request is live mode or test mode.

Authentication

To authorize, use this code:

curl "API_ENDPOINT" -H "Authorization: Bearer API_TOKEN"

The Chronomics API uses API tokens to authenticate requests.

The tokens do not expire and cary many privileges so be sure to keep them secure.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

For authorization add the header Authorization: Bearer {{API_TOKEN}}. Where {{API_TOKEN}} is a long lived token application token that will be provided to you.

Errors

Chronomics uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (i.e. validation or authentication error). Codes in the 5xx range indicate an error with Chronomics's servers.

200 - OK
400 - Validation error
401 - Authentication error
429 - Too Many Requests
500 - Something went wrong on Chronomics side

Orders

Orders allow you to order tests which will be delivered directly to your end customers.

Create Order

curl --location --request POST "https://api.stage.chronomics.com/v1/order" \
-H "Authorization: Bearer API_TOKEN" \
--form 'product=covid-gbp' \
--form 'quantity=1' \
--form 'num_returns_labels=1' \
--form 'delivery_fname=Bob' \
--form 'delivery_lname=Jones' \
--form 'delivery_address1=My House' \
--form 'delivery_city=London' \
--form 'delivery_postcode=N1 6HH' \
--form 'delivery_country=GB' \
--form 'email=email@gmail.com' \
--form 'mobile_country=44'
--form 'mobile=77777777777'
--form 'notes='

The above command returns JSON structured like this:

{
"status": true,
"order_id": 895,
"order_number": "TT598"
}

Creates a new order for a kit that will be dispatched in the post.

You must have account based billing setup with Chronomics in order to create orders through the API.

The customer will be informed by email once the kit is dispatched.

POST /order

Parameters

ParameterDescription
product(required, string) The type of kit you are ordering. Valid products are: covid-gbp, covid-fit-to-fly-gbp, covid-ttr-gbp, travel-amber-gbp, travel-green-gbp or biological-age-yearly-gbp
quantity(required, int) The quantity of kits to order to this address.
num_returns_labels(required, int) The number of returns labels required. If you order more than one kit and want to return them individual use this to specify.
delivery_fname(required, string) Customer delivery first name.
delivery_lname(required, string) Customer delivery last name.
delivery_address1(required, string) Customer delivery address line 1.
delivery_address2(optional, string) Optional address line 2.
delivery_city(required, string) Customer delivery city.
delivery_postcode(required, string) Customer delivery postcode or zipcode.
delivery_country(required, string) Customer delivery country. 2 character ISO code.
email(required, string) Customer email. Used for delivery updates.
mobile_country(required, string) Customer mobile country code, ie 44.
mobile(required, string) Customer mobile number. Required by the courier for delivery.
notes(optional, string) Any addational notes.
travel_country(optional, string) Required for travel products. The country traveling to or from. 2 character ISO code.
travel_outbound_departure_date(optional, string) Required for fit to fly. Format: YYYY-MM-DD
travel_return_departure_date(optional, string) Required for travel products. Date on which you last departed from or transited through a non-exempt country or territory not on the travel corridors list. Format: YYYY-MM-DD
travel_return_arrival_date(optional, string) Required for travel products. Date of arrival in the UK. Format: YYYY-MM-DD
travel_return_flight_number(optional, string) Required for travel products. Flight number, coach or vessel name.
travel_return_transit_countries(optional, string) Optional list of countires you transited through. Provide a comma seperated list.
travel_passengers(optional, array) Required for travel products. Array of people traveling. Inclucde each as object {passport_fname: 'First and middle name', passport_lname: 'Last Name'} exactly as appears on passport.

Update a Order

curl --location --request POST "https://api.stage.chronomics.com/v1/order/:id" \
-H "Authorization: Bearer API_TOKEN" \
--form 'delivery_fname=Sam' \
--form 'delivery_lname=Smith' \

The above command returns JSON structured like this:

{
"status": true,
"order_id": 895,
"order_number": "TT598"
}

Updates a order. Only pass in the details you want to update - everything else will remain the same.

Orders may be updated with 1 hour of placing, or up to 3pm before the day of dispatch (for kits that dispatch on futured dates).

If you need to modify the product or quantity, please cancel the order and place again.

POST /order

Parameters

ParameterDescription
delivery_fname(optional, string) Customer delivery first name.
delivery_lname(optional, string) Customer delivery last name.
delivery_address1(optional, string) Customer delivery address line 1.
delivery_address2(optional, string) Optional address line 2.
delivery_city(optional, string) Customer delivery city.
delivery_postcode(optional, string) Customer delivery postcode or zipcode.
delivery_country(optional, string) Customer delivery country. 2 character ISO code.
email(optional, string) Customer email. Used for delivery updates.
mobile_country(optional, string) Customer mobile country code, ie 44.
mobile(optional, string) Customer mobile number. Required by the courier for delivery.
notes(optional, string) Any addational notes.
travel_country(optional, string) Required for travel products. The country traveling to or from. 2 character ISO code.
travel_outbound_departure_date(optional, string) Required for fit to fly. Format: YYYY-MM-DD
travel_return_departure_date(optional, string) Required for travel products. Date on which you last departed from or transited through a non-exempt country or territory not on the travel corridors list. Format: YYYY-MM-DD
travel_return_arrival_date(optional, string) Required for travel products. Date of arrival in the UK. Format: YYYY-MM-DD
travel_return_flight_number(optional, string) Required for travel products. Flight number, coach or vessel name.
travel_return_transit_countries(optional, string) Optional list of countires you transited through. Provide a comma seperated list.

Cancel a Order

curl --location --request POST "https://api.stage.chronomics.com/v1/order/:id/cancel" \
-H "Authorization: Bearer API_TOKEN"'

The above command returns JSON structured like this:

{
"status": true,
}

Cancels a order. User the order_id rather than order_number as this may not be unique.

Orders may be canceled with 1 hour of placing, or up to 3pm before the day of dispatch (for kits that dispatch on futured dates).

POST /order/:id/cancel

Tests

Object representing a Chronomics test. May differ depending on the type of test it is and the state the test is in.

Retrieve COVID-19 tests

curl --request GET "https://api.stage.chronomics.com/v1/results/covid" \
-H "Authorization: Bearer API_TOKEN" \

The above command returns JSON structured like this:

{
"status": true,
"data": [
{
"test_id": 166,
"fname": "Bob",
"lname": "Jones",
"email": "email@chronomics.com",
"user_id": 213,
"order_number": "FR567",
"sampled_at": "2020-06-26 10:08:59",
"registered_at": "2020-06-26 11:00:00",
"processed_at": "2020-06-26 11:00:00",
"result": "negative"
},
{
"test_id": 165,
"fname": "Rob",
"lname": "Thompson",
"email": "cxcxcd@fddf.com",
"user_id": 213,
"order_number": "AD933",
"sampled_at": "2020-06-26 10:06:13",
"registered_at": "2020-06-26 11:00:00",
"processed_at": "2020-06-27 09:01:00",
"result": "positive"
}
]
}

Returns a list of all COVID-19 test results, or registered tests. Returns orered by registered_at desc.

There may be more that one row per user if they have done more than one test.

GET /results/covid

URL Parameters

ParameterDescription
status(required, string) The status of the tests you want, one of registered or results
name(optional, string) Filter by customer name.
order_number(optional, string) Filter by order number.
date_registred_after(optional, date) Only show tests registered after this date. Format YYYY-MM-DD.
date_results_after(optional, date) Only show tests with results after this date. Format YYYY-MM-DD.
limit(optional, int) Number of results to show. Default 100, maximum 500.

Labs

Common functionality related to labs communicating with Chronomics.

Test recieved

curl --request POST 'https://api.stage.chronomics.com/v1/labs/tests/received' \
-H 'Authorization: Bearer API_TOKEN' \
--form 'barcode=56361095719740' \
--form 'received_at=2020-01-01T10:10:10Z'

The above command returns JSON structured like this:

{
"status": true
}

Mark test as recieved at the lab.

The barocde must exist in the Chronomics system for this to be sucsefull.

POST /labs/tests/received

Parameters

ParameterDescription
barcode(required, string) Unique barcode identifying this sample.
received_at(required, datetime) ISO 8601 date and time this test was recieved ie '2020-01-01T10:10:10Z'.

Test Results

curl --request POST "https://api.stage.chronomics.com/v1/labs/tests/result" \
-H "Authorization: Bearer API_TOKEN" \
--form "barcode=56361095719740" \
--form "result=negative" \
--form "test_type=covid19_salivir_multiplex" \
--form "sample_type=saliva" \
--form "received_at=2020-01-01T10:10:10Z" \
--form "to_repeat=0" \
--form 'extra_data={"cq": 1.33}' \
--form "comments="

The above command returns JSON structured like this:

{
"status": true,
"added": 1
}

Add test results once processed.

If tests are due to be repeated say due to a fail or inconclusive, they should be reported in the first instance with to_repeat flag and then again on the repeat result.

POST /labs/tests/result

Parameters

ParameterDescription
barcode(required, string) Unique barcode identifying this sample.
result(required, string) The result of the test, one of positive, negative, failed, inconclusive, detected, not detected, not processed.
result_concentration(required - antibody only, numeric) The result of antibody test in U/mL.
test_type(required, string) The type of test this is, one of covid19_salivir_multiplex, roche_elecsys_anti_sars_cov_2_s.
sample_type(required, string) The type of sample, one of saliva, nps, venous.
received_at(optional, datetime) ISO 8601 date and time this test was recieved ie '2020-01-01T10:10:10Z'.
processed_at(required, datetime) ISO 8601 date and time this test was processed ie '2020-01-01T10:10:10Z'.
to_repeat(optional, integer) Boolean flaging if this test is due to be repeated (ie as it failed first time) 0=no repeate, 1=repeat.
extra_data(optional, string) Any extra data on the test, ie CQ values. Json encoded.
comments(optional, string) Any addational comments about the test, ie the reason for failing.