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.
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.
01$ curl https://api.hive.id/token \-H "Authorization: Basic [YOUR API KEY]:[YOUR API SECRET]"
0123{"access_token": "jiHzJf7DyZgVK0u-sDx1wc2FrsyOdkcDD48YE3EBXtI.c01qkYBHs3-cCW1D8EvuYQBvkTKjccY_SglOOyx9ymk","expires_in": 3599}
Creates an access token.
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 the access_token if the creation succeeded. Returns an error if create parameters are invalid.
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.
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}
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 yyyy-mm-dd 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.
0123$ curl https://api.hive.id/customers \-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk" \-d email="john@hive.id" \-X POST
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.
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 yyyy-mm-dd format.
metadata optional Set of key-value pairs that you can attach to a customer.
Returns the customer object if the creation succeeded. Returns an error if create parameters are invalid.
01$ curl https://api.hive.id/customers \-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk"
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.
No parameters.
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.
01$ curl https://api.hive.id/customers/8462e8ce-4245-4eca-835c-4a160b93b030 \-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk"
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.
No parameters.
Returns a customer object if a valid identifier was provided.
0123$ curl https://api.hive.id/customers/8462e8ce-4245-4eca-835c-4a160b93b030 \-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk" \-d middle_name="Farrell" \-X PATCH
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.
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 yyyy-mm-dd format.
metadata optional Set of key-value pairs that you can attach to a customer.
Returns the customer object if the update succeeded. Returns an error if update parameters are invalid.
012$ curl https://api.hive.id/customers/8462e8ce-4245-4eca-835c-4a160b93b030 \-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk" \-X DELETE
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.
No parameters.
Returns a deleted customer object if a valid identifier was provided. Returns an error if the customer identifier does not exist.
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.
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}
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
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
012{"session_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyb29tIjoiVXRpbzEzNmh0R1VBIiwic2Vzc2lvbl9pZCI6ImQ4Nzc5MjAMmU3ODUwYjY5NiIsImlhdCI6MTYwMjI0ODYxNCwiZXhwIjoxNjAyMjUyMjE0fQ.UZeshLxicEOjL8vBlka32S-hRH47XCD2TlUvp1qzGNs"}
Creates a new session, which can be used to initialize the Hive SDKs.
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 the session_token if the creation succeeded. Returns an error if create parameters are invalid.
01$ curl https://api.hive.id/sessions \-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk"
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.
No parameters.
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.
01$ curl https://api.hive.id/sessions/d8779205-f122-4325-af25-942e7850b696 \-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk"
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.
No parameters.
Returns a session object if a valid identifier was provided.
012$ curl https://api.hive.id/sessions/d8779205-f122-4325-af25-942e7850b696 \-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk" \-X DELETE
012{"id": "d8779205-f122-4325-af25-942e7850b696"}
Permanently deletes a session. This cannot be undone.
No parameters.
Returns an object with a deleted parameter if a valid identifier was provided. Returns an error if the session identifier does not exist.
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.
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}
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.
0123$ curl https://api.hive.id/checks \-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk" \-d session_id="d8779205-f122-4325-af25-942e7850b696" \-X POST
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.
session_id required Unique identifier of the completed session.
Returns the check object if the creation succeeded. Returns an error if create parameters are invalid.
01$ curl https://api.hive.id/checks \-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk"
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.
No parameters.
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.
01$ curl https://api.hive.id/checks/db3590ce-3121-4b0d-9839-733709727f7b \-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk"
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.
No parameters.
Returns a check object if a valid identifier was provided.
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.
01$ curl https://api.hive.id/checks/db3590ce-3121-4b0d-9839-733709727f7b/report \-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk"
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.
No parameters.
Returns a report object if a valid identifier was provided.
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).
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}
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.
01$ curl https://api.hive.id/files \-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk"
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.
No parameters.
A dictionary with a data property that contains an array of files. Each entry in the array is a separate file object.
01$ curl https://api.hive.id/files/e1e0cdc7-5c10-4fe9-85c8-18add6596ef0 \-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk"
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.
No parameters.
Returns a file object if a valid identifier was provided.