Skip to main content

Getting started

In this section:

Here you can find information on how to integrate with the Controlant Cold-Chain monitoring Integrations API. A recommended checklist for setting up your Controlant Integrations API and making the most of it.

Getting started with the Controlant Integrations API is a two step process, but we recommend setting everything up for the UAT environment first, and then moving to the LIVE environment:

Step 1: Obtain an API key

To get an API key, contact your Customer Success Manager.

Step 2: Authenticate

See Authentication

Step 3: Make a test call to the API

See Making a test call to the API

Next steps

Now that you’ve got basic connectivity set up, you’ll want to explore making calls to the other endpoints in the system as well as determining your error handling process.

See also:

Authentication

The Integrations API uses an access key based authentication and authorization exchange that we refer to as API keys.

Each client can use one or more API keys to authenticate their communication with the Integrations API. Each request the client makes must include an API key in the Authorization header of the request.

curl -X POST \
     -H "Authorization: APIKey MYAPIKEY" \
     -H "Content-Type: application/json" \
     -H "x-api-version: 1" \
     -d '{"reference": "Testing echo"}' \
     https://integrations.uat.controlant.com/api/echo

Note

All requests must contain the x-api-version header. Currently only the value 1 is supported.

$ curl -H 'x-api-version: 1' -X https://integrations.controlant.com/api/echo

Getting authentication credentials

To get a new API key, modify, disable, or delete existing API keys, contact your Controlant contact.

You can have one or more API keys configured and set up to suit your integration scenarios.

  • We recommend configuring everything using the UAT environment, and switching over to LIVE only when everything is working as it should.

    Note

    You will need to request new API keys for the LIVE environment.

  • All API keys are created with the status of active, which means that you can immediately use them to access API functions.

  • When you disable an access key, you cannot use it for API calls.

  • When you delete an access key, it's gone forever and cannot be retrieved.

  • We recommend that you analyze your integration needs and determine how many API keys you require and how you are planning to implement your API key rotation. For more information, see API key management.

Making a test call to the API

The Integrations API offers special endpoints intended to test connectivity.

UAT test endpoint

<https://integrations.uat.controlant.com/api/echo>

LIVE test endpoint

<https://integrations.controlant.com/api/echo>

These endpoints will validate your API Key and can also produce all known response formats and error conditions the Integrations API can return.

When everything is set up correctly you are ready to make a test request.

Example request

curl -X POST \
     -H "Authorization: APIKey MYAPIKEY" \
     -H "Content-Type: application/json" \
     -H "x-api-version: 1" \
     -d '{"reference": "Test-Echo-Request-01"}' \
     https://integrations.uat.controlant.com/api/echo

Example response

< HTTP/1.1 200 OK
< Date: Tue, 18 Feb 2025 13:26:31 GMT
< Content-Type: application/json; charset=utf-8
< Server: Kestrel
< Content-Length: 144
< x-correlation-id: fa60ac03-c54a-4fee-9675-3c09e948083c
{
  "reference": "Test-Echo-Request-01",
  "success": true,
  "message": "Hi there :). The time is now: 2025-02-18T13:26:32.1678719+00:00"
}

Example error request

curl -X POST \
     -H "Authorization: APIKey MYAPIKEY" \
     -H "Content-Type: application/json" \
     -H "x-api-version: 1" \
     -d '{"reference": "500 Error"}' \
     https://integrations.uat.controlant.com/api/echo

Example error response

< HTTP/1.1 500 Internal Server Error
< Date: Wed, 28 Feb 2025 16:23:54 GMT
< Content-Type: application/json
< Transfer-Encoding: chunked
< Connection: keep-alive
< Server: Kestrel
< x-correlation-id: 0c9f600d-c1ec-460a-9299-c5d089a22762
{
    "errorMessage": "Internal Error in Integrations API",
    "status": 500,
    "success": false,
    "responseTime": 0
}

Error responses and how to handle them

We highly recommend planning ahead and deciding how to handle the following known error conditions that the Controlant Integrations API can return for a request.

Handling known API errors

Each request to the API returns a predefined standard HTTP status. This status indicates whether the request was processed successfully, and if not, what type of error occurred.

The HTTP status can take one of the following values:

API error statuses

Status

Response

Description

200

Successful

No errors.

400

Validation error

Input data does not conform to the API specifications for this function.

Please see the response for details on the error. Retrying with the same arguments will not work.

401

Authentication error

The API Key could not be validated.

404

Not found

The requested resource could not be found but may be available again in the future, make sure the requested URL is correct.

500

Server-side error

Server side error, unexpected condition was encountered.

Sometimes this is the result of a coding or configuration error made by Controlant.

504

Internal communication server-side error

Temporary internal connectivity issue. It is safe to retry the action in a few minutes.

Example HTTP error response

< HTTP/1.1 401 Unauthorized
< Date: Mon, 17 Feb 2025 13:00:12 GMT
< Server: Kestrel
< Content-Length: 0
< WWW-Authenticate: APIKey error=No APIKey authentication header value found
< x-correlation-id: 982411d3-1d9a-432b-8b98-fcb611c44fae

Note

All responses return a CorrelationId that should be logged by the caller and used when referring to the issue with Controlant.

For more information about CorrelationId, see Debugging techniques.

Validation errors (HTTP Status 400)
curl -X POST \
     -H "Authorization: APIKey MYAPIKEY" \
     -H "Content-Type: application/json" \
     -H "x-api-version: 1" \
     https://integrations.uat.controlant.com/api/echo

< HTTP/1.1 400 Bad Request
< Date: Tue, 18 Feb 2025 12:52:17 GMT
< Content-Type: application/json; charset=utf-8
< Server: Kestrel
< Content-Length: 271
< x-correlation-id: 8c4cfeb4-6d2a-491c-b201-74773d9de3db
Authentication errors (HTTP Status 401)
curl -X POST \
     -H "Content-Type: application/json" \
     -H "x-api-version: 1" \
     -d '{"reference": "Test-Echo-Request-01"}' \
     https://integrations.uat.controlant.com/api/echo

< HTTP/1.1 401 Unauthorized
< Date: Tue, 18 Feb 2025 12:55:13 GMT
< Server: Kestrel
< Content-Length: 0
< WWW-Authenticate: APIKey error=No APIKey authentication header value found
< x-correlation-id: 2dd695d3-69ed-44b5-8894-472abcafab01
Unexpected Server errors (HTTP Status 500 and 504)

The Integration API declares two possible error states that can be returned for unexpected server-side errors. Both of these scenarios share the same message format.

curl -X POST \
     -H "Authorization: APIKey MYAPIKEY" \
     -H "Content-Type: application/json" \
     -H "x-api-version: 1" \
     -d '{"reference": "500 Error"}' \
     https://integrations.uat.controlant.com/api/echo

< HTTP/1.1 500 Internal Server Error
< Date: Tue, 18 Feb 2025 13:18:42 GMT
< Content-Type: application/json
< Server: Kestrel
< Transfer-Encoding: chunked
< x-correlation-id: 9652c916-6caf-4aae-97a9-a07ca92a81e6

Next steps

Debugging techniques

Here you can find information that is useful for debugging issues that may come up.

Tracking requests using correlation identifiers

The Controlant Integrations API is built up of several asynchronous system components and to facilitate easier message tracking through various components it uses the correlation identifier or Correlation ID pattern.

Each incoming request is issued a unique identifier that is carried with it through all internal system components and used to identify various system generated requests/ responses originating from a single incoming client request.

curl -X POST \
     -H "Authorization: APIKey MYAPIKEY" \
     -H "Content-Type: application/json" \
     -H "x-api-version: 1" \
     -H 'X-Correlation-Id: {GUID}' \
     -d '{"reference": "Test-Echo-Request-01"}' \
     https://integrations.uat.controlant.com/api/echo

The X-Correlation-Id header is always returned with all HTTP responses. We advise you to log this value in your systems for reference if issues arise.

Note

You can choose to either include the X-Correlation-Id header with your initial request or omit it and the Integrations API will generate one.

Caller supplied Correlation Ids

We highly encourage clients working with larger multi-system integration solutions to consider supplying the Integrations API with your own generated Correlation Id.

By maintaining your own Correlation Id values you can track requests as they pass through multiple integration system providers and use the Correlation Id as the main tracking code when tracking data flow issues or errors in large asynchronous integration system networks.

The Integrations API will honor all Correlation Id values passed to it by its callers and return the same value back in all HTTP responses.

Controlant supplied Correlation Ids

If the request does not include a Correlation Id, the Integrations API will generate one, and that Correlation Id header is always returned with all HTTP responses.

We advise you to log this value in your systems for reference in case issues arise.

Before integrating

Before setting up the integration, it’s helpful to go through the following checklist:

Note

All new customers receive an initial questionnaire from Controlant and the next steps are prepared by the Controlant integration team based on the replies.

  • Shipments, locations, and templates require unique reference ids. These references must be unique to the customer, i.e. no two shipments should have the same reference. We recommend that reference fields are created using data that has contextual and business meaning to the customer. This value is usually visible to multiple stakeholders in the customer supply chain (shipment reference is for example prominently displayed on shipment labels and quality reports).

  • A detailed understanding of the data flow between customer systems is necessary. Also establishing an understanding of how the customer packing operations work with regards to the Controlant device placements.

  • For each integration call, identify which event in the customer system should trigger the integration call to the Controlant platform. This could for example be clear goods-issued signals or triggered after packing according to the usual workflow for the customer.

  • Logger handling unit assignments and arrangements must be clear. Either a single logger per shipment or multiple loggers per shipment. Also, other details on single handling unit (HU) as well, such as possible splitting of HU during shipment and customer operational procedures related to HU splitting.

  • The location data used for the origin and delivery location assignments are required. The quality of the address data on the customer side as well as the availability of geolocation information (GPS) for each address.

    Example: Decision on automated delivery and sent trigger states. If you wish to use geofencing capabilities, accurate geo-location information is required. Also, configuration information for the various templates is listed in later sections of this manual.

  • Configuration of templates is customer-specific and depends on your needs and requirements.

    Example: The wake-up interval for loggers can be configured differently for different shipping modes (typically you will want longer wake-up intervals for ocean shipments, and shorter for road transport). Customer requirements on updates to shipment data during transit, such as properties or product assignments.

  • Other customer-specific data should be known.