Cryos API documentation - Delivery note API

This page contains a brief description of the Cryos International DeliveryNote API and a few illustrative examples that demonstrate how delivery notes, represented as JSON objects, are retrieved from the API.

The DeliveryNote API is an OData RESTful API that enables 3rd party developers to easily query data using standard OData request options such as $filter, $select, $expand among other options.

As this page only goes through a few request examples, for a more comprehensive description of all supported OData options, we advise you to visit the API section in the Cryos International API Portal. This section of the portal also provides a built-in web client that allows you try out the API before integrating it in your software.

Accessing the DeliveryNote API

To successfully access the API, you will need to use the following URL and add your subscription key in the request header:

https://platform.cryosinternational.com/deliverynote/DeliveryNotes

In addition to adding your subscription key in the request header, you will also need to provide a clinic’s API key. This will grant you access to delivery notes regarding a specific clinic. Both API keys are described in more detail in the following table.

Omitting the clinic apiKey in the request header or adding a malformed apiKey will result in (HTTP) 400 Bad Request with the following message in the response body:

HTTP response body

Access denied due to invalid api key. Make sure to provide a valid api key.

A similar message is returned if you omit your subscription key in the request.

The DeliveryNote API EntitySet

In this section we will briefly cover the entity-sets and entities returned by the DeliveryNote API.

The API returns the DeliveryNotes entity-set, which consists of a list of DeliveryNote entities regarding a clinic. A DeliveryNote entity may or may not contain a collection of DeliveryLines, which itself consists of a list of related DeliveryLine entities. The following hierarchy illustrates this:

+ DelveiryNotes
+ DeliveryNote
- RecipientName
- …
+ DeliveryLines
- DeliveryLine
- DeliveryLine
+ DeliveryNote
- RecipientName
- …
+ DeliveryLines

For a more detailed description of the DeliveryNote and DeliveryLine entities and their properties

HTTP Request Examples

In this section we will go through a few examples that demonstrate how the DeliveryNote API is queried using ODATA. These examples will cover the most essential queries. For more advanced queries consult the online OData documentation.

In the first example, we will start out by querying all DeliveryNotes for a given clinic. The following is the HTTP GET request and the required keys in the request header:

GET https://platform.cryosinternational.com/deliverynote/DeliveryNotes
apiKey: <A clinic’s api key>
Ocp-Apim-Subscription-Key: <Your subscription key>

This request fetches all DeliveryNotes for a given clinic, identified by it’s apiKey, while the Ocp-Apim-Subscription-key is used to authenticate you. The following is the JSON object from the response body:

As depicted above, the HTTP response body contains a collection of all DeliveryNotes for a given clinic. Notice how the DeliveryLines collections are not included in the DeliveyNote entities. This is standard OData behavior for collections-sets containing complex types. To load related entities, the OData $expand option can be used to include them inline.

In the following example we use the $expand option to load all DeliveryNotes and their DeliveryLines:

GET https://platform.cryosinternational.com/deliverynote/DeliveryNotes?$expand=DeliveryLines
apiKey: <A clinic’s api key>
Ocp-Apim-Subscription-Key: <Your subscription key>

As can be seen above, the response body now includes all DeliveryLine entities. Take note that the DeliveryNote API only supports one level of expansion i.e. only the DeliveryLines entity-set is expandable.

In the last example we will look at the $filter option and see how we can use it to conditionally query DeliveryNotes:

GET https://cryos.azure-api.net/deliverynote/DeliveryNotes?$expand=DeliveryLines&$filter=Timestamp gt 2014-04-24T11:00:00.0000000Z
apiKey: <A clinic’s api key>
Ocp-Apim-Subscription-Key: <Your subscription key>

In the example above, the $filter option is used to conditionally query all DeliveryNotes where the Timestamp property is greater than 2015-04-24T11:00:00.0000000Z i.e. we are interested in detecting DeliveryNotes updated after a given date. This example also includes the DeliveryLines entity-set using the $expand option from the previous example.

In the response above, the result is filtered down to one DeliveryNote by using the $Top filter set to 1.

The $filter option is quite advanced and can be used with any property. It can also be used in nested queries with the $expand option e.g. to conditionally filter on DeliveryLine properties.

SOR (Summary of records)

The deliveryNote API supports for PDF retrieval of an orders summary of records which is a report that is generated for each donor containing all the donors test results. This endpoint DeliveryNotes('{orderNumber}')/OrderSummaryOfRecords will generate a merged pdf file for all donors SOR in a specific order. In order to get this file you have to put in an ordernumber and as with the standard deliveryNote endpoint call have the clinic key/api key in order to retrieve the SOR pdf file.