This article is for those who access Umbra through the api/v2 endpoint by using tokens and api keys for authentication. If you access Umbra in other ways please see the other Umbra articles in this section instead.
Accessing our data and setting headers:
You will need an api key and an authorization token from us. Enter the api key into the field labeled x-api-key. Enter the token into the field labeled Authorization. This should be in the format Bearer Token-We-Gave-You. The accept header will usually be application/json, except for when you are expecting an image back, such as in photoDownload. Then it will be image/png. Here's an example of headers in an axios call with the the keys and tokens replaced with XXX:
Here's an example of the same thing using curl instead:
This is the expected response:
Get Events for a Suspect
The call above demonstrates how to get suspect details. The call below demonstrates how to get event details for the same suspect
Note that param v1: ‘true’ is required here to avoid an error. This is the expected response:
Checking System Health
If these calls are not working for you try checking system health:
Running a Face Search
Step 1:
Expected Response:
Step 2:
Use the seachId returned in step 1 and enter it as sessionId:
Expected Results:
In this case the targetId under referencePhoto for an individual entry on the list is what you will need to enter as the suspectId if you want to call details or events for a suspect.
Other Possible Results:
In the case of an unknown or pending answer please wait a bit and try step 2 again.
Running a Text Search
Step 1:
Expected Response:
Step 2:
Use the searchId returned in step 1 as the sessionId
Expected Response:
In this case the comparisonId for an individual entry on the list is what you will need to enter as the suspectId if you want to call suspect details for an entry.
Viewing Your Search History:
Set ascending to True. It will currently throw an error without this. All other parameters are optional. A successful result will contain an array of search objects. It will also tell you the number of search objects available under total.
Expected Results:
Download a Photo
Step 1 - Find A Photo Id
You can find a photo id in a person entry by looking in the photo array in that person entry. Find the id field for each entry within the array.
In some cases you will also find photos within the event results. In event results select a result then expand an individual result and look for arrestBinderList. Expand the references within arrestBinderList. Some of these references may be photos. Others may be information such as facility or arrestNumber.
Step 2:
Expected Response:
This should return 200 Success with a photo.
Upload a Photo
A successful response will contain an id field in the result. This is what you will reference if you are going to use this photo later, for example to detect a face or download the photo.
Detect a Face in a Photo
In order to detect a face in a photo you will need a photo id. If you don’t have a photo id yet, then upload the photo as described in the step above and use the id in the response to that call.
Expected Response:
This successful result indicates this photo may be a useful photo to run an image search with. See ‘How To Do An Image Search' section above.
If a face was not found you should expect this:
{ "status": "NOT_FOUND", "result": "No Face Detected" }
with a 404 status response. This indicates that an image search will not be successful using this photo because we cannot detect a face in it.