API Docs

URL prefix for all API endpoints:

https://api.connect.verifyyou.com

POST /v1/business_connect_user/register

Registers a new or, if that user exists, returned their verified status

Request

• Headers:

  {
    "Content-Type": "application/json"
    "API-KEY": "<your-api-key>"
  }
  

• Body:

  {
    "reference_user_id": "string", // A unique ID for this user
    "redirect_url": "string", // (optional) URL to your site to send a user to once they're verified
    "data_request": "data_request object" // required to specify the data being requested from that user - see docs for formatting
  }
  

Response

• Success:

  {
    "status": "success",
    "invite_url": "string",        // The URL for the invite to be displayed as QR code and/or a link to click
    "user_id": "string",           // VerifyYou's unique ID for this user
    "connection_verified": "bool",  // Indicates if the connection is verified.
  }
  

• Failure:

  {
    "status": "failure",
    "failure_code": "string",       // The code representing the type of failure.
    "failure_reason": "string"      // A description of the failure reason.
  }
  

POST /v1/business_connect_user/check_connection_status

Checks the connection status and, if available, retrieves a data request for registered user. A data request includes information about the user that was requested of and approved by the user, such as if they are over 18 years old.

Request

• Headers:

  {
    "Content-Type": "application/json"
    "API-KEY": "<your-api-key>"
  }
  

• Body:

  {
    "reference_user_id": "string",
  }
  

Response

• Success:

  {
    "status": "success",
    "has_connection": true,                     // Indicates if the user has a connection.
    "encrypted_data_request_response": "string" // The data the company requested from the user, encrypted
                                                // with the Decryption Private Key as described below. For example (decrypted),
                                                // {"result": True, "type": "IS_AT_LEAST_AGE", "years": 18}
  }
  

• Failure: Will return DOES_NOT_EXIST on an unregistered user

  {
    "status": "failure",
    "failure_code": "string",             // The code representing the type of failure.
    "failure_reason": "string"            // A description of the failure reason.
  }
  

Decrypting encrypted_data_request_response

encrypted_data_request_response is encrypted with libsodium's Sealed Box method, which uses X25519 and XSalsa20-Poly1305. (See: https://libsodium.gitbook.io/doc/public-key_cryptography/sealed_boxes). In this case, a shared key is not established, but rather just a public-key cryptography scheme. The private key to use is the Decryption Private Key we supplied. Here's a simple Python example that shows how to decrypt encrypted_data_request_response.

Note: This code requires the PyNaCl Python library.

from base64 import b64decode, b64encode
from json import dumps, loads
from nacl.public import PrivateKey, PublicKey, SealedBox

# Key generation

example_private_key = '6WEYVJyliVI4zkCJqFylOx6xLY0T4drZCUvnCv1izmw='

# Simulate getting an encrypted_data_request_response from VerifyYou

def get_simulated_encrypted_data_request_response():
  example_public_key = 'BMULmmu/jVQGza1luiH0mpJAl/9mlcOtskLVDOJdMiw='
  def encrypt(text, public_key):
    unboxed_public_key = PublicKey(b64decode(public_key))
    sealed_box = SealedBox(unboxed_public_key)
    encrypted_message = sealed_box.encrypt(text.encode('utf-8'))
    return b64encode(encrypted_message).decode('utf-8')
  text = dumps([{"result": True, "type": "IS_AT_LEAST_AGE", "years": 18}])
  return encrypt(text, example_public_key)

# Decrypt an encrypted_data_request_response from VerifyYou

def decrypt(cipher, private_key):
  unboxed_private_key = PrivateKey(b64decode(private_key))
  sealed_box = SealedBox(unboxed_private_key)
  decrypted_message = sealed_box.decrypt(b64decode(cipher))
  return decrypted_message.decode('utf-8')

encrypted_data_request_response = get_simulated_encrypted_data_request_response()
data_request_response_json = decrypt(encrypted_data_request_response, example_private_key)
data_request_response = loads(data_request_response_json)
print('data_request_response:', data_request_response)