Trying the BioID Web Service REST API with cURL

event_note May 22, 2015

Let's try to do some hands-on REST with the BioID Web Service (BWS). You'll need to already have requested a trial instance. Then you can go to the BWS Management portal and register a client app. I did this and got an email telling me that it runs on storage bws with in partition 9184. After having created it I can see that it appears in the “Client Apps” tab with the identifier The app name is something you can choose yourself when registering a new one.

BWS Portal

One last thing we need to get started is the password for accessing the BWS. You can get it by clicking on the edit button if you did not write it down initially. There, you can also request a new password—which is what I will do before posting this article.

For me, it spells KNGypodPwU9KYddwJRODxftP.

Give me a token

Now we're all set and as a first thing, point your browser of choice to You see that the assigned partition appears twice, once as the subdomain and once in the BCID-Parameter.

The BCID (Biometric Class ID) should be unique for every user. We'd normally spell it bws/9184/42, but for the REST service also accepts bws.9184.42, as forward slashes might look confusing. The BCID consists of the storage (bws), the partition (9184) and the user who we are inquiring about. This last part can be chosen freely. But beware that giving the same ID to several users or giving returning users new IDs basically sabotages everything.

What the browser displays is a plain-text string that—in my case—looks like this:

bSIsImV4cCI6MTQzMTk1NDI3NiwibmJmIjoxNDMxOTUzNjc2fQ.xrih0Rkaojaz UcqRSM-TlDirzDIY4TTxMa7ps1CQ_k4

This is your token that you'll need to do further inquiries about that user. We can also use the command line to get it. Assuming you have cURL installed, this will download the token to a text file:

curl -u "" >token.txt

Anybody there?

Next, let's see if we already enrolled face images (we could also ask for voice) for user 42:

curl -vu ""

We have to use verbose mode (notice the -v switch) to see that we get back a HTTP/1.1 404 Not Found at the end of a lot of output and that means that we did not.

May I introduce…

Let's upload some pictures first. I have two gray-scale PNG images that I want to send. We need to convert them to a data URL first, which can easily be done here.

dataset sample 1dataset sample 2

After that, uploading is easy:

curl -H "Authorization: Bearer eyJ0eXAiOi…nu6DIkS2Go" -d @a.png.txt
curl -H "Authorization: Bearer eyJ0eXAiOi…nu6DIkS2Go" -d @b.png.txt

I shortened the token part, because it's really long, but you have to put all of it working. For both images I got the answer


After that, we tell the web service that these two files should be enrolled for the user 42. We don't have to specify the BCID again, because all this is encoded in the token.

curl -H "Authorization: Bearer eyJ0eXAiOi…nu6DIkS2Go"

Again, I get no error, which means that we have successfully enrolled our first user!



For a quick check:

curl -vu ""

gives a HTTP 200, which is what we expect. After getting a new token with task=verify (the old one invalidated anyway after one use) we can upload a third image of the same face and see if it is recognized.

curl -u "" >token.txt

dataset sample 3

curl -H "Authorization: Bearer eyJ0eXAiOi…nRyhs0P1SY" -d @c.png.txt
curl -H "Authorization: Bearer eyJ0eXAiOi…nRyhs0P1SY"

All commands succeed and I'm happy.