API Reference

Hive's API (Application Programming Interface) powers its Identity platform. The API is organized around REST and uses standard HTTP response codes, verbs and token-based authentication. Returns JSON-encoded responses.

Authentication

All requests to the Hive servers must be authenticated. The API uses token-based authentication. API tokens must be included in the header of all requests made to the API.

To begin, obtain the API Key and API Secret from the Hive Dashboard. Then your server application requests an access token from the Token Endpoint, extracts the token from the response, and sends the token to the Hive API that you want to access.

Your API keys carry many privileges. For that reason, they must remain confidential and secure! Do not share your secret API keys in publicly accessible areas such as git repositories and client-side code, or with anyone, including our support team.

API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Retrieve an access token

curl
01
$ curl https://api.hive.id/token \
-H "Authorization: Basic [YOUR API KEY]:[YOUR API SECRET]"
GET
/token
response
0123
{
"access_token": "jiHzJf7DyZgVK0u-sDx1wc2FrsyOdkcDD48YE3EBXtI.c01qkYBHs3-cCW1D8EvuYQBvkTKjccY_SglOOyx9ymk",
"expires_in": 3599
}

Creates an access token.

Parameters

The token endpoint supports HTTP Basic authentication. The Authorization header of this request must contain Base 64 encoded string with the API Key and API Secret. The field must have the format: Authorization: Basic 'base64 encoded API KEY:API SECRET'.

Returns

Returns the access_token if the creation succeeded. Returns an error if create parameters are invalid.

Customers

POST
GET
GET
PATCH
DELETE
/customers
/customers
/customers/{id}
/customers/{id}
/customers/{id}

A Customer represents an individual who will be the subject of a verification check. A customer must exist before a check can be initiated.

The API allows you to create, delete, and update your customers. You can retrieve individual customers as well as a list of all your customers.

The Customer object

the customer object
0123456789101112
{
"id": "8462e8ce-4245-4eca-835c-4a160b93b030",
"email": "john@hive.id",
"phone": null,
"first_name": "John",
"middle_name": null,
"last_name": "Doe",
"gender": null,
"dob": null,
"metadata": {},
"created_at": 1602241760,
"updated_at": 1602241760
}

Attributes

id string Unique identifier for the object.

email string Customer’s email address. It’s displayed alongside the customer in your Dashboard and can be useful for searching.

phone string Customer’s phone number. Can be used to run additional checks on the customer.

first_name string Customer’s first name.

last_name string Customer’s last name.

middle_name string Customer’s middle name.

gender string Customer’s gender - International regulations require either “male” or “female”.

dob string Customer's date of birth in dd-mm-yyyy format.

metadata object Set of key-value pairs that you can attach to a customer. This can be useful for storing additional information about the customer in a structured format.

created_at timestamp Time at which the customer was created. Measured in seconds since the Unix epoch.

updated_at timestamp Time at which the customer was last updated. Measured in seconds since the Unix epoch.

Create a customer

curl
0123
$ curl https://api.hive.id/customers \
-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk" \
-d email="john@hive.id" \
-X POST
POST
/customers
response
0123456789101112
{
"id": "8462e8ce-4245-4eca-835c-4a160b93b030",
"email": "john@hive.id",
"phone": null,
"first_name": null,
"middle_name": null,
"last_name": null,
"gender": null,
"dob": null,
"metadata": {},
"created_at": 1602241760,
"updated_at": 1602241760
}

Creates a new customer object.

Parameters

email required Customer's email address.

phone optional Customer's phone number.

first_name optional Customer's first name.

last_name optional Customer's last name.

middle_name optional Customer's middle name.

gender optional Customer's gender.

dob optional Customer's date of birth in dd-mm-yyyy format.

metadata optional Set of key-value pairs that you can attach to a customer.

Returns

Returns the customer object if the creation succeeded. Returns an error if create parameters are invalid.

List all customers

curl
01
$ curl https://api.hive.id/customers \
-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk"
GET
/customers
response
01234567891011121314151617
{
"data": [{
"id": "8462e8ce-4245-4eca-835c-4a160b93b030",
"email": "john@hive.id",
"phone": null,
"first_name": "John",
"middle_name": null,
"last_name": "Doe",
"gender": null,
"dob": null,
"metadata": {},
"created_at": 1602241760,
"updated_at": 1602241760
}],
"meta": {
"total": 1
}
}

Returns a list of your customers. The customers are returned sorted by creation date, with the most recent customers appearing first.

Parameters

No parameters.

Returns

A dictionary with a data property that contains an array of customers. Each entry in the array is a separate customer object. This request should never return an error.

Retrieve a customer

curl
01
$ curl https://api.hive.id/customers/8462e8ce-4245-4eca-835c-4a160b93b030 \
-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk"
GET
/customers/{id}
response
0123456789101112
{
"id": "8462e8ce-4245-4eca-835c-4a160b93b030",
"email": "john@hive.id",
"phone": null,
"first_name": "John",
"middle_name": null,
"last_name": "Doe",
"gender": null,
"dob": null,
"metadata": {},
"created_at": 1602241760,
"updated_at": 1602241760
}

Retrieves the details of an existing customer. You only need to supply the unique customer identifier.

Parameters

No parameters.

Returns

Returns a customer object if a valid identifier was provided.

Update a customer

curl
0123
$ curl https://api.hive.id/customers/8462e8ce-4245-4eca-835c-4a160b93b030 \
-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk" \
-d middle_name="Farrell" \
-X PATCH
PATCH
/customers/{id}
response
0123456789101112
{
"id": "8462e8ce-4245-4eca-835c-4a160b93b030",
"email": "john@hive.id",
"phone": null,
"first_name": "John",
"middle_name": "Farrell",
"last_name": "Doe",
"gender": null,
"dob": null,
"metadata": {},
"created_at": 1602241760,
"updated_at": 1602241760
}

Updates the specified customer by setting the values of the parameters passed. Any parameters not provided will be left unchanged.

This request accepts mostly the same arguments as the customer creation call.

Parameters

email optional Customer's email address.

phone optional Customer's phone number.

first_name optional Customer's first name.

last_name optional Customer's last name.

middle_name optional Customer's middle name.

gender optional Customer's gender.

dob optional Customer's date of birth in dd-mm-yyyy format.

metadata optional Set of key-value pairs that you can attach to a customer.

Returns

Returns the customer object if the update succeeded. Returns an error if update parameters are invalid.

Delete a customer

curl
012
$ curl https://api.hive.id/customers/8462e8ce-4245-4eca-835c-4a160b93b030 \
-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk" \
-X DELETE
DELETE
/customers/{id}
response
0123456789101112
{
"id": "8462e8ce-4245-4eca-835c-4a160b93b030",
"email": "john@hive.id",
"phone": null,
"first_name": "John",
"middle_name": "Farrell",
"last_name": "Doe",
"gender": null,
"dob": null,
"metadata": {},
"created_at": 1602241760,
"updated_at": 1602241760
}

Permanently deletes a customer. This cannot be undone. Also deletes any checks or reports associated with the customer.

Parameters

No parameters.

Returns

Returns a deleted customer object if a valid identifier was provided. Returns an error if the customer identifier does not exist.

Sessions

POST
GET
GET
DELETE
/sessions
/sessions
/sessions/{id}
/sessions/{id}

A Session enables customers to send personal data to Hive via one of our SDKs. A session must be created BEFORE the SDK is initialized. All of the SDKs authenticate using session tokens, which are represented as JSON Web Tokens (JWT).

Session tokens are restricted to an individual customer and expire after 90 minutes, and therefore can be safely used on the client side (web or mobile applications). We recommend that you create exactly one session for each submission attempt.

The Session object

the session object
0123456789101112
{
"id": "d8779205-f122-4325-af25-942e7850b696",
"customer": "8462e8ce-4245-4eca-835c-4a160b93b030",
"full_name": "John Farrell Doe",
"email": "john@hive.id",
"application_id": "417c1928-05ac-45dd-8740-9e4a996f823e",
"workspace_id": "53f87c6e-7242-4a5b-ac65-33fba6e247a0",
"status": "completed",
"expires_at": 1602241889,
"created_at": 1602238289,
"updated_at": 1602238325,
"check_id": null
}

Attributes

id string Unique identifier for the object.

customer string Customer’s unique identifier.

full_name string Customer’s full name.

email string Customer’s email address.

application_id string

workspace_id string

status string

expires_at timestamp Time at which the session will expire. Measured in seconds since the Unix epoch.

created_at timestamp Time at which the session was created. Measured in seconds since the Unix epoch.

updated_at timestamp Time at which the session was last updated. Measured in seconds since the Unix epoch.

check_id string

Create a session

curl
01234
$ curl https://api.hive.id/sessions \
-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk" \
-d customer_id="8462e8ce-4245-4eca-835c-4a160b93b030" \
-d application_key="hWsqWCs7fS4nfKW1cYevw7fxKLKTN78a" \
-X POST
POST
/sessions
response
012
{
"session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb29tIjoiVXRpbzEzNmh0R1VBIiwic2Vzc2lvbl9pZCI6ImQ4Nzc5MjAMmU3ODUwYjY5NiIsImlhdCI6MTYwMjI0ODYxNCwiZXhwIjoxNjAyMjUyMjE0fQ.UZeshLxicEOjL8vBlka32S-hRH47XCD2TlUvp1qzGNs"
}

Creates a new session, which can be used to initialize the Hive SDKs.

Parameters

customer_id required ID of the Customer this Session belongs to, if one exists.

application_key required Application key to be used with the SDK. Can be obtained in the Hive Dashboard.

Returns

Returns the session_token if the creation succeeded. Returns an error if create parameters are invalid.

List all sessions

curl
01
$ curl https://api.hive.id/sessions \
-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk"
GET
/sessions
response
01234567891011121314151617
{
"data": [{
"id": "d8779205-f122-4325-af25-942e7850b696",
"customer": "8462e8ce-4245-4eca-835c-4a160b93b030",
"full_name": "John Farrell Doe",
"email": "john@hive.id",
"application_id": "417c1928-05ac-45dd-8740-9e4a996f823e",
"workspace_id": "53f87c6e-7242-4a5b-ac65-33fba6e247a0",
"status": "completed",
"expires_at": 1602241889,
"created_at": 1602238289,
"updated_at": 1602238325,
"check_id": null
}],
"meta": {
"total": 1
}
}

Returns a list of sessions.

Parameters

No parameters.

Returns

A dictionary with a data property that contains an array of sessions. Each entry in the array is a separate session object. This request should never return an error.

Retrieve a session

curl
01
$ curl https://api.hive.id/sessions/d8779205-f122-4325-af25-942e7850b696 \
-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk"
GET
/sessions/{id}
response
0123456789101112
{
"id": "d8779205-f122-4325-af25-942e7850b696",
"customer": "8462e8ce-4245-4eca-835c-4a160b93b030",
"full_name": "John Farrell Doe",
"email": "john@hive.id",
"application_id": "417c1928-05ac-45dd-8740-9e4a996f823e",
"workspace_id": "53f87c6e-7242-4a5b-ac65-33fba6e247a0",
"status": "completed",
"expires_at": 1602241889,
"created_at": 1602238289,
"updated_at": 1602238325,
"check_id": null
}

Retrieves the details of an existing session. You only need to supply the unique session identifier.

Parameters

No parameters.

Returns

Returns a session object if a valid identifier was provided.

Delete a session

curl
012
$ curl https://api.hive.id/sessions/d8779205-f122-4325-af25-942e7850b696 \
-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk" \
-X DELETE
DELETE
/sessions/{id}
response
012
{
"id": "d8779205-f122-4325-af25-942e7850b696"
}

Permanently deletes a session. This cannot be undone.

Parameters

No parameters.

Returns

Returns an object with a deleted parameter if a valid identifier was provided. Returns an error if the session identifier does not exist.

Checks

POST
GET
GET
DELETE
/checks
/checks
/checks/{id}
/checks/{id}

Checks are performed on a customer upon completion of the SDK flow (web or mobile). A check consists of one or more reports.

The API allows you to create and delete checks. You can retrieve individual checks as well as a list of all your checks.

The Check object

the check object
012345678
{
"id": "db3590ce-3121-4b0d-9839-733709727f7b",
"session_id": "d8779205-f122-4325-af25-942e7850b696",
"status": "processing",
"decision": null,
"report": null,
"created_at": 1602251909,
"updated_at": 1602251909
}

Attributes

id string Unique identifier for the object.

session_id string Customer’s session unique identifier.

status string

decision string

report string

created_at timestamp Time at which the check was created. Measured in seconds since the Unix epoch.

updated_at timestamp Time at which the check was last updated. Measured in seconds since the Unix epoch.

Create a check

curl
0123
$ curl https://api.hive.id/checks \
-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk" \
-d session_id="d8779205-f122-4325-af25-942e7850b696" \
-X POST
POST
/checks
response
012345678
{
"id": "db3590ce-3121-4b0d-9839-733709727f7b",
"session_id": "d8779205-f122-4325-af25-942e7850b696",
"status": "processing",
"decision": null,
"report": null,
"created_at": 1602251909,
"updated_at": 1602251909
}

Creates a new check. Can be created upon the completion of a session.

Parameters

session_id required Unique identifier of the completed session.

Returns

Returns the check object if the creation succeeded. Returns an error if create parameters are invalid.

List all checks

curl
01
$ curl https://api.hive.id/checks \
-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk"
GET
/checks
response
012345678910111213
{
"data": [{
"id": "db3590ce-3121-4b0d-9839-733709727f7b",
"session_id": "d8779205-f122-4325-af25-942e7850b696",
"status": "processing",
"decision": null,
"report": null,
"created_at": 1602251909,
"updated_at": 1602251909
}]
"meta": {
"total": 1
}
}

Returns a list of checks.

Parameters

No parameters.

Returns

A dictionary with a data property that contains an array of checks. Each entry in the array is a separate check object. This request should never return an error.

Retrieve a check

curl
01
$ curl https://api.hive.id/checks/db3590ce-3121-4b0d-9839-733709727f7b \
-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk"
GET
/checks/{id}
response
012345678
{
"id": "db3590ce-3121-4b0d-9839-733709727f7b",
"session_id": "d8779205-f122-4325-af25-942e7850b696",
"status": "processing",
"decision": null,
"report": null,
"created_at": 1602251909,
"updated_at": 1602251909
}

Retrieves the details of an existing check. You only need to supply the unique check identifier.

Parameters

No parameters.

Returns

Returns a check object if a valid identifier was provided.

Reports

GET
/checks/{id}/report

Any check you create on a customer results in a report.

A report provides a granular understanding of your customer, different data attributes (traits) collected during a verification session, the authenticity and similarity of those traits and overall identity assessment.

Retrieve a report

curl
01
$ curl https://api.hive.id/checks/db3590ce-3121-4b0d-9839-733709727f7b/report \
-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk"
GET
/checks/{id}/report
response
0123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231
{
"id": "d93fc999-d1bd-4a72-94f2-a7de39e6edb9",
"check_id": "08296bee-f9e5-47b1-8a62-6e60d10f262d",
"version": 1,
"result": "caution",
"processed": 1593445509,
"submitted": 1593445496,
"generated": 1602254253,
"document_report": {
"status": "consider",
"data_consistency": {
"status": "caution",
"document_number": {
"status": "clear"
},
"date_of_expiry": {
"status": "caution"
},
"date_of_birth": {
"status": "clear"
},
"personal_number": {
"status": "clear"
},
"surname": {
"status": "clear"
},
"given_names": {
"status": "clear"
},
"gender": {
"status": "clear"
},
"surname_and_given_names": {
"status": "clear"
}
},
"data_validation": {
"status": "consider",
"document_number": {
"status": "caution"
},
"date_of_expiry": {
"status": "caution"
},
"date_of_issue": {
"status": "clear"
},
"date_of_birth": {
"status": "clear"
},
"gender": {
"status": "clear"
},
"mrz": {
"status": "consider"
}
},
"document_visual_authenticity": {
"status": "clear",
"template": {
"status": "clear"
},
"fonts": {
"status": "clear"
},
"face_detection": {
"status": "clear"
},
"security_features": {
"status": "clear"
}
},
"properties": {
"document_title": "identity card",
"year": "2018",
"icao_code": "EST",
"country_name": "Estonia",
"document_class_code": "ID",
"issuing_state_code": "EST",
"document_number": "AS1234567",
"date_of_expiry": "02.01.2020",
"date_of_issue": "09.08.2018",
"date_of_birth": "08.01.1980",
"place_of_birth": "EST",
"personal_number": "38001085718",
"surname": "JOEORG",
"given_names": "JAAK KRISTJAN",
"nationality": "EST",
"gender": "M",
"surname_and_given_names": "JOEORG JAAK KRISTJAN",
"nationality_code": "EST",
"mrz_type": "ID-1",
"mrz_name": "38001085718",
"issuing_state_name": "Estonia",
"mrz_strings": "IDESTAS1234567138001085718<<<<^8001081M2001023EST<<<<<<<<<<<3^JOEORG<<JAAK<KRISTJAN<<<<<<<<<",
"document_number_checkdigit": "1",
"date_of_birth_checkdigit": "1",
"date_of_expiry_checkdigit": "3",
"finalcheckdigit": "3",
"card_access_number": "345678",
"mrz_strings_with_correct_checksums": "IDESTAS1234567238001085718<<<<^8001081M2001023EST<<<<<<<<<<<3^JOEORG<<JAAK<KRISTJAN<<<<<<<<<",
"age": "40",
"months_to_expire": "0"
}
},
"facial_report": {
"status": "caution",
"image_integrity": {
"status": "clear",
"brightness": {
"status": "clear"
},
"sharpness": {
"status": "clear"
}
},
"face_comparison": {
"status": "caution",
"similarity": {
"status": "caution"
},
"age_range": {
"status": "clear"
},
"gender": {
"status": "clear"
}
},
"visual_authenticity": {
"status": "clear",
"liveness": {
"status": "clear"
},
"emotion": {
"status": "clear"
}
},
"properties": {
"gender": "Male",
"emotions": [
"CALM"
],
"age_range": "19 - 37",
"beard": true,
"mustache": false,
"eyeglasses": false,
"live": true,
"liveness": 0.99992394,
"faces_match": false,
"similarity": 0,
"brightness": 69.33,
"sharpness": 89.85
}
},
"customer_report": {
"status": "caution",
"ip": {
"status": "caution",
"tor": {
"status": "clear"
},
"vpn": {
"status": "clear"
},
"web_proxy": {
"status": "clear"
},
"public_proxy": {
"status": "clear"
},
"spam_blacklist": {
"status": "caution"
}
},
"device_fingerprint": {
"status": "clear",
"fingerprint_authenticity": {
"status": "clear"
},
"fingerprint_attempted_fraud": {
"status": "clear"
}
},
"properties": {
"email": {},
"phone": {},
"mobile": {
"fraud_score": 2,
"proxy_score": 0,
"device_hash": "66d7914268a814399409c88f271ed11a",
"platform": "iPhone",
"os": "iOS",
"user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Mobile/15E148 Safari/604.1",
"browser": "MOBILE_SAFARI",
"browser_version": "14.0",
"region_language": "ru-ua",
"region_timezone": "+03:00",
"screen_resolution": "896x414",
"screen_color_depth": 32,
"screen_pixel_ratio": 2,
"ip": "94.153.12.54",
"country": "UA",
"type": "ISP/MOB",
"latitude": 50.62308,
"longitude": 26.22743,
"spam_number": 1
},
"desktop": {
"fraud_score": 0,
"proxy_score": 0,
"device_hash": "28784090d930b94944b9e68f95d451b7",
"platform": "MacIntel",
"os": "MacOS",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.106 Safari/537.36",
"browser": "CHROME8",
"browser_version": "83.0.4103.106",
"region_language": "ru-RU",
"region_timezone": "+03:00",
"screen_resolution": "1792x1120",
"screen_color_depth": 30,
"screen_pixel_ratio": 2,
"ip": "94.153.12.54",
"country": "UA",
"type": "ISP/MOB",
"latitude": 50.62308,
"longitude": 26.22743,
"spam_number": 1
}
}
}
}

Retrieves the details of a report. You only need to supply the unique check identifier.

Parameters

No parameters.

Returns

Returns a report object if a valid identifier was provided.

Files

GET
GET
/files
/files/{id}

File object represents a file (image of an identity document or the customer's face) stored on Hive's servers.

The files may have been uploaded by your customer using the SDK or they may have been created by Hive (during recognition and verification process).

The File object

the file object
01234567
{
"id": "e1e0cdc7-5c10-4fe9-85c8-18add6596ef0",
"type": "portrait",
"metadata": {},
"url": "https://files.hive.id/downloads/e1e0cdc7-5c10-4fe9-85c8-18add6596ef0",
"check": "bbcc830a-e15e-4cf1-9746-98016d9fdb19",
"created_at": 1601084628
}

Attributes

id string Unique identifier for the object.

type string

metadata object Set of key-value pairs that you can attach to a file. This can be useful for storing additional information about the file in a structured format.

url string The URI that can be used to download the file.

check string Unique identifier for the associated check.

created_at timestamp Time at which the file was uploaded. Measured in seconds since the Unix epoch.

List all files

curl
01
$ curl https://api.hive.id/files \
-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk"
GET
/files
response
0123456789101112
{
"data": [{
"id": "e1e0cdc7-5c10-4fe9-85c8-18add6596ef0",
"type": "portrait",
"metadata": {},
"url": "https://files.hive.id/downloads/e1e0cdc7-5c10-4fe9-85c8-18add6596ef0",
"check": "bbcc830a-e15e-4cf1-9746-98016d9fdb19",
"created_at": 1601084628
}],
"meta": {
"total": 1,
}
}

Returns a list of files.

Parameters

No parameters.

Returns

A dictionary with a data property that contains an array of files. Each entry in the array is a separate file object.

Retrieve a file

curl
01
$ curl https://api.hive.id/files/e1e0cdc7-5c10-4fe9-85c8-18add6596ef0 \
-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk"
GET
/files/{id}
response
01234567
{
"id": "e1e0cdc7-5c10-4fe9-85c8-18add6596ef0",
"type": "portrait",
"metadata": {},
"url": "https://files.hive.id/downloads/e1e0cdc7-5c10-4fe9-85c8-18add6596ef0",
"check": "bbcc830a-e15e-4cf1-9746-98016d9fdb19",
"created_at": 1601084628
}

Retrieves the details of an existing file. You only need to supply the unique file identifier.

Parameters

No parameters.

Returns

Returns a file object if a valid identifier was provided.

GuideAPI ReferenceGitHubTwitter