General Information

To sign up and get credentials to use this api please contact sales@biometrica.com.

UMbRA is Biometrica’s Unique Mission to Build Records and Arrests. It is our 100% law enforcement-sourced, multi-jurisdictional real-time NatCrime database, modeled on the NCIC, with search capabilities that allow searches in seconds against textual (name + other demographic) and photographic (Face Rec) parameters, including from mobile devices in the field. Data in UMbRA is updated on an hourly basis from jurisdictions across the United States. To request a demo: Law Enforcement, contact leo@biometrica.com; non-law enforcement, contact: marketing@biometrica.com

For specific questions please see our frequently asked questions link below.

FAQ: https://support.biometrica.com/hc/en-us/sections/115000509473-FAQ

Accessing Our Data - Setting Headers

This Readme guides you through accessing our api through the Rapid API user interface under the Endpoints tab of our API listing. Rapid API conveniently provides you with code snippits that you can copy to place into your code once you’ve made sure that it is working using the Test Endpoint button.

When accessing our endpoints through Rapid API expand the Header Parameters section. You will need an api key and an authorization token from us. Enter the api key into the field labled x-api-key. Enter the token into the field labled 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. User-agent should be rapidapi. Rapid API key and host should be supplied through Rapid API.

How To Do A Text Search

Step 1

In our endpoints expand search#complex and select postSearch. Fill in the headers as described above. Fill in the body of the request as needed. The body is required, but not all fields in the body are required. For example, the following is acceptable:

{ "type": "match", "searchText": "john doe", "referenceId": "", "comparisonId": "", "maxMatches": 10, "matchThreshold": 1, "collectionId": "umbra", "frApplication": "Rekognition" }

Depending on your search you should expect one of the following responses:

{ "status": "SUCCESS", "description": "", "result": { "searchId": "string" } }

or

{ "status": "ERROR", "description": "string" }

Step 2

If you receive a successfull result you can use the searchId returned to look up the search results. Copy the searchId not including the quotes surrounding it, and in our endpoints expand search and select frTryGetResults. Expand required parameters and paste this id into the sessionId field. A successful result will be in json and contain a list of possible matches in this format:

{ "status": "SUCCESS", "description": "", "result": { "results": [

where results is an array containing search results as objects.

Other possible results include:

{ "status": "PENDING", "description": "", "result": [] }

{ "status": "UNKNOWN", "description": "", "result": [] }

{ "status": "TIMEOUT", "description": "", "result": [] }

{ "status": "ERROR", "description": "", "result": [] }

In the case of an unknown or pending answer please wait a bit and try step 2 again. For more on what to do with the information contained in a successful result please see ‘How To Get Details On One Entry’ below. In this case the comparisonId for an individual entry on the list is what you will need to enter as the suspectId. Remember, if doing this through the Rapid API user interface testing section just copy the id without the quotation marks.

How To Do An Image Search

Step 1

In our endpoints expand search#instant and select postInstantSearch. Fill in the headers as described above. In request body select a photo file and a match threshold. The photos most likely to be successful are face forward headshots. The following file types will work .jpeg, .jpg, and .png.

Depending on your search you should expect one of the following responses:

{ "status": "SUCCESS", "description": "", "result": { "searchId": "string" } }

or

{ "status": "ERROR", "description": "string" }

Step 2

If you receive a successfull result you can use the searchId returned to look up the search results. Copy the searchId not including the quotes surrounding it, and in our endpoints expand search and select frTryGetResults. Expand required parameters and paste this id into the sessionId field. A successful result will be in json and contain a list of possible matches in this format:

{ "status": "SUCCESS", "description": "", "result": { "results": [

where results is an array containing search results as objects.

Other possible results include:

{ "status": "PENDING", "description": "", "result": [] }

{ "status": "UNKNOWN", "description": "", "result": [] }

{ "status": "TIMEOUT", "description": "", "result": [] }

{ "status": "ERROR", "description": "", "result": [] }

In the case of an unknown or pending answer please wait a bit and try step 2 again. For more on what to do with the information contained in a successful result please see ‘How To Get Details On One Entry’ below. In this case the targetId under referencePhoto for an individual entry on the list is what you will need to enter as the suspectId. Remember, if doing this through the Rapid API user interface testing section just copy the id without the quotation marks.

How To Get Details On One Entry

Step 1

To get details on one entry you will need the id of that entry. This may be from an image search you just did, a text search you just did, or a search in your search history.

In a list of image search results look for the targetId under referencePhoto in an individual entry on your search results.

In a list of text search results look for the comparisonId for an individual entry on the list of results.

In our endpoints list expand suspects and select getSuspect. Fill in the headers as instructed above. Paste the id into the suspectId field in parameters. Do not wrap it in quotes.

A successful restult will look like this:

{ "status": "SUCCESS", "description": "", "result": { "id": "string", "firstName": "string", "middleName": "string", "lastName": "string", "prefix": "string", "suffix": "string", "dateOfBirth": "string", "fullName": "string", "description": "string", "aliases": [ {} ], "photos": [ { "id": "string" } ] } }

Step 2

To get events for this person go to our endpoints list, expand suspects and select getSuspectEventData. Fill in the headers as described above. Use the same suspectId under parameters. Using the dropdown under parameters set v1 to True. It will throw an error without this. The rest of the parameters are optional. You may set them if you wish. Keep in mind that some people have a large number of events. Default limit is 10, but many have more than 10 on file. A successfull result will look like this:

{ "status": "SUCCESS", "description": "", "start": 0, "limit": 0, "total": 0, "result": [ { "id": "string", "eventType": "arrest", "suspect_id": "string", "dispositionBinderList": [ { "id": "string", "type": "string", "data": { "facility": "string", "eventDate": "string", "database": "string" } } ], "arrestBinderList": [ { "id": "string", "address": "string", "age": 0, "arrestDate": "string", "arrestNumber": "string", "arrestingAgency": "string", "arrestingOfficer": "string", "badge": "string", "bondAgency": "string", "bookingDate": "string", "dateOfBirth": "string", "dateReleased": "string", "event_id": "string", "facility": "string", "inmateClassification": "string", "zipCode": "string", "lastUpdateDate": "string", "references": [ { "key": "string", "value": "string" } ] } ], "caseBinderList": [ { "id": "string", "arrestNumber": "string", "bondAmount": 0, "bondType": "string", "caseId": 0, "caseNumber": "string", "courtTime": "string", "event_id": "string", "fineAmount": 0, "sentence": "string", "status": "string", "lastUpdateDate": "string", "references": [ { "key": "string", "value": "string" } ] } ], "chargeBinderList": [ { "id": "string", "arrestCode": "string", "arrestDate": "string", "arrestNumber": "string", "arrestingAgency": "string", "bondAmount": 0, "bondType": "string", "caseNumber": "string", "chargeDescription": "string", "chargeId": 0, "chargeStatus": "string", "controlNumber": "string", "courtTime": "string", "courtType": "string", "crimeTYpe": "string", "event_id": "string", "offenseDate": "string", "warrantNumber": "string", "lastUpdateDate": "string", "references": [ { "key": "string", "value": "string" } ] } ] } ] }

How To 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

In our endpoint list expand photos and select photoDownload. Set the headers as usual and paste the photo id from step one into the photoId field under parameters. If you are using the rapid api user interface you should see a photo appear in the results body area to the right.

How To View Your Search History

Go to our endpoint list and expand search. Select listSearchHistory. Fill in headers as described above. Expand parameters. Set ascending to True. It will currently throw and 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.

How To Upload A Photo

Go to our endpoint list and expand photos. Select photoUpload. Enter the headers as described above. The content-type in this case should be multipart/form-data. When using the user interface use the choose file button to choose a photo. As you can see in the code snippet window, when doing this in code you will want to create a formdata like so:

`const fs = require(‘fs’);

const FormData = require(‘form-data’);

const data = new FormData();

data.append(‘file’, fs.createReadStream(’/PATH/TO/537C.jpeg’));`

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.

How To 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. If you already have an id go to our endpoints and expand photos. Select detectFaceInPhoto. Set the headers as usual and paste the photo id into the photoId field under parameters. The app field is not required. A successful result will return a 200 meaning a face was detected, or a 404 meaning a face was not found.

If a face was found you should expect data in this format:

{ "status": "SUCCESS", "description": "", "result": [ {} ] }

This successful result indicates this photo may be a useful photo to run an image search with. See ‘How To Do An Image Seach’ 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.