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 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.

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 yyyy-mm-dd 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 yyyy-mm-dd 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
012345678910111213
{
"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",
"check_id": null,
"intent": null,
"status": "completed",
"expires_at": 1602241889,
"created_at": 1602238289,
"updated_at": 1602238325
}

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

check_id string

intent 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.

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
0123456789101112131415161718
{
"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",
"check_id": null
"intent": null,
"status": "completed",
"expires_at": 1602241889,
"created_at": 1602238289,
"updated_at": 1602238325,
}],
"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
012345678910111213
{
"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",
"check_id": null
"intent": null,
"status": "completed",
"expires_at": 1602241889,
"created_at": 1602238289,
"updated_at": 1602238325
}

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
01234567
{
"id": "db3590ce-3121-4b0d-9839-733709727f7b",
"session_id": "d8779205-f122-4325-af25-942e7850b696",
"status": "processing",
"decision": 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

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
01234567
{
"id": "db3590ce-3121-4b0d-9839-733709727f7b",
"session_id": "d8779205-f122-4325-af25-942e7850b696",
"status": "processing",
"decision": 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
0123456789101112
{
"data": [{
"id": "db3590ce-3121-4b0d-9839-733709727f7b",
"session_id": "d8779205-f122-4325-af25-942e7850b696",
"status": "processing",
"decision": 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
01234567
{
"id": "db3590ce-3121-4b0d-9839-733709727f7b",
"session_id": "d8779205-f122-4325-af25-942e7850b696",
"status": "processing",
"decision": 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
0123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235
{
"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",
"reason": "MRZ (02.01.2020) and Visual (02.02.2020) don't match"
},
"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",
"reason": "Visual data (AS1533567) is not valid"
},
"date_of_expiry": {
"status": "caution",
"reason": "Visual data (02.02.2020) is not valid"
},
"date_of_issue": {
"status": "clear"
},
"date_of_birth": {
"status": "clear"
},
"gender": {
"status": "clear"
},
"mrz": {
"status": "MRZ is not valid"
}
},
"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": "consider",
"reason": "Faces don't match (5%)"
},
"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.

Download a file

curl
01
$ curl https://files.hive.id/downloads/e1e0cdc7-5c10-4fe9-85c8-18add6596ef0 \
-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk"
GET
/downloads/{id}

Parameters

No parameters.

Returns

Returns a file if a valid identifier was provided.

Webhooks

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

The Webhook object

json
0123456789
{
"id": "44a56725-de93-4759-a3c3-1885fcd6e868",
"endpoint": "https://example.com/webhook",
"workspace": "53f87c6e-7242-4a5b-ac65-33fba6e247a0",
"type": "check.completed",
"is_active": true,
"is_sandbox": false,
"created_at": 1594915712,
"updated_at": 1594915712
}

Attributes

id string Unique identifier for the object.

endpoint string

workspace string

type string

is_active boolean

is_sandbox boolean

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 webhook

curl
012345
$ curl https://api.hive.id/webhooks \
-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk" \
-d endpoint="https://example.com/webhook" \
-d type="check.completed" \
-d is_sandbox=false \
-X POST
POST
/webhooks
response
0123456789
{
"id": "44a56725-de93-4759-a3c3-1885fcd6e868",
"endpoint": "https://example.com/webhook",
"workspace": "53f87c6e-7242-4a5b-ac65-33fba6e247a0",
"type": "check.completed",
"is_active": true,
"is_sandbox": false,
"created_at": 1594915712,
"updated_at": 1594915712
}

Creates a new webhooks object.

Parameters

endpoint required

type required

is_sandbox required

Returns

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

List all webhooks

curl
01
$ curl https://api.hive.id/webhooks \
-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk"
GET
/webhooks
response
01234567891011121314
{
"data": [{
"id": "44a56725-de93-4759-a3c3-1885fcd6e868",
"endpoint": "https://example.com/webhook",
"workspace": "53f87c6e-7242-4a5b-ac65-33fba6e247a0",
"type": "check.completed",
"is_active": true,
"is_sandbox": false,
"created_at": 1594915712,
"updated_at": 1594915712
}],
"meta": {
"total": 1
}
}

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

Parameters

No parameters.

Returns

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

Update a webhook

curl
0123
$ curl https://api.hive.id/webhook/8462e8ce-4245-4eca-835c-4a160b93b030 \
-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk" \
-d is_active=false \
-X PATCH
PATCH
/webhooks/{id}
response
0123456789
{
"id": "44a56725-de93-4759-a3c3-1885fcd6e868",
"endpoint": "https://example.com/webhook",
"workspace": "53f87c6e-7242-4a5b-ac65-33fba6e247a0",
"type": "check.completed",
"is_active": false,
"is_sandbox": false,
"created_at": 1594915712,
"updated_at": 1594915712
}

Updates the specified webhook 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 webhook creation call.

Parameters

endpoint required

type required

is_sandbox required

Returns

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

Delete a webhook

curl
012
$ curl https://api.hive.id/webhooks/8462e8ce-4245-4eca-835c-4a160b93b030 \
-H "Authorization: Bearer jiHzJf7DyZ...yx9ymk" \
-X DELETE
DELETE
/webhooks/{id}
response
0123456789
{
"id": "44a56725-de93-4759-a3c3-1885fcd6e868",
"endpoint": "https://example.com/webhook",
"workspace": "53f87c6e-7242-4a5b-ac65-33fba6e247a0",
"type": "check.completed",
"is_active": false,
"is_sandbox": false,
"created_at": 1594915712,
"updated_at": 1594915712
}

Permanently deletes a webhook. This cannot be undone.

Parameters

No parameters.

Returns

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

HomeVerifyAPI ReferenceGitHubTwitter