referenceId #

The referenceId is an optional request parameter which can be used to add a custom identifier to a request. This allows for easily retrieving specific requests in the Blicker portal, using your own custom scheme.

Note that this is different from the requestId. The request ID is generated by Blicker and is unique to every request. The reference ID may be generated by the sender, is optional, can follow any scheme, and is not necessarily unique for every single request.

Best practices #

It is common for an organization to already have a unique reference for a required meter reading. As an example, let’s say that a certain end-user is identified by the index “123456”, and that this end-user has to register its meter reading for the 14th time, which makes that the unique reference for this meter reading is identified by “123456-14” in the database of your organization. This string can then be passed as the reference ID when the end-user takes an image of its meter and sends it to the Blicker reading endpoint.

In some cases, multiple requests may be sent to the Blicker reading endpoint for a single meter reading. For example because the end-user did not sent a correct image, or because Blicker was unable to read out the correct meter reading on the first try. In such cases, you could send each request with the same reference ID. This allows to easily retrieve all attempts in the Blicker portal. Note that each request will still have a unique request ID. Another option would be to send the first request, for example, with reference ID “123456-14-try-1”, a second try with “123456-14-try-2”, etc.

Example request #

curl -X 'POST' \
  'https://api.blicker.ai/blicker/2020-10-01' \
  -H 'subscription-key: <your subscription key>' \
  -F 'image=@test_image.jpg' \
  -F 'referenceId=123456-14'

from pathlib import Path
from pprint import pprint

import requests

response = requests.post(
    "https://api.blicker.ai/blicker/2020-10-01",
    headers={"subscription-key": "<your subscription key>"},
    files={"image": ("test_image.jpg", Path("test_image.jpg").read_bytes())},
    data={"referenceId": "123456-14"},
)

pprint(response.json())

If a reference ID is provided in the request, the response will contain the same referenceId at the top-level.