API Documentation

Glossary

• reference_id: A local reference ID for the user based on the client naming scheme. Used to register and query users.
• unique_id: A uuid ID for the user generated by VerifyYou and mapped to the reference_id. Can be used in place of a reference_id to query users after registration.
• invite_id: The ID associated with an invite sent to the user, used internally by VerifyYou.
• invite_url: The URL for the invite, to be given to the user.
• connection_verified: Indicates if the connection is verified.
• data_request_response: The response data for the data request, adheres to the data request format interface.
• last_refresh_timestamp_s: The timestamp of the last refresh in seconds.

REST Calls

POST /v1/business_connect_user/register

Registers a new connect user or pulls the latest on an existing one.

Request

• Headers:
  • Content-Type: application/json
  • API-KEY: <your-api-key>
• Body:

  {
    "reference_id": "string",   // A reference ID for the user.
  }
  

Response

• Success:

  {
    "status": "success",
    "unique_id": "string",          // The unique ID of the business connect user [autogenerated]
    "invite_id": "string",          // The invite ID associated with the user.
    "invite_url": "string",         // The URL for the invite.
    "connection_verified": true     // 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 pulls down data request for registered user.

Request

• Headers:
  • Content-Type: application/json
  • API-KEY: <your-api-key>
• Body:

  {
    "reference_id": "string",
    // or
    "unique_id": "string"
  }
  

Response

• Success:

  {
    "status": "success",
    "unique_id": "string",                
    "has_connection": true,               // Indicates if the user has a connection.
    "data_request_response": "string"     // The response data for the data request.
  }
  

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

POST /v1/business_connect_user/check_for_updates

Checks for updates on the connection status of business connect users.

Request

• Headers:
  • Content-Type: application/json
  • API-KEY: <your-api-key>
• Body:

  {
    "last_refresh_timestamp_s": "integer"  // The timestamp of the last refresh in seconds.
  }
  

Response

• Success:

  {
    "status": "success",
    "connections_to_update": ["string"],  // A list of user names whose connections need to be updated.
    "timestamp_s": "integer"              // The current timestamp in seconds.
  }
  

• Failure:

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

Webhooks

Webhook Overview

Webhooks allow you to receive real-time HTTP notifications of changes to user verification status. When an event occurs, a POST request is sent to the webhook URL you have configured.

Events

Each webhook is called from the configured url with the corrosponding even appended onto the path. For now all payloads are the same but future version may give customers optional control fo their keys to facilitate end to end encryption.

• /connection_verified - successful verification of a user
• /connection_deleted - user deleted their verification or account
• [COMING SOON] /deverification - called upon user deverification by VerifyYou for fraud

Request

• Headers:
  • Content-Type: application/json
  • X-Hub-Signature-256: sha256=<hmac-signature> // HMAC signature for verifying the payload.
• Body:

  {
    "payload": {                // The payload recieved in the webhook.
      "event": "string",        // Event code - see above (sans /)
      "unique_id": "string",
      "reference_id": "string",
    }
  }
  

The request will try up to 3 times at exponential dropoff or until recieving a 200 return code.

Verifying Webhook Signature

To verify the webhook signature, compare the hashed payload with the enclosed signature using your shared secret. Here's an example of that process in python:

import hashlib
import hmac
import base64

def verify_signature(payload, secret, signature):
    computed_signature = hmac.new(
        secret.encode('utf-8'),
        payload.encode('utf-8'),
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(computed_signature, signature)

Configuration

Coming soon. For now send Axel the url and he'll send you a secret