API References

General Integration (v1)

Overview

The General Integration option connects your system directly to Vcheck's platform, allowing you to submit investigation requests. This solution is flexible, accommodating different JSON data formats, allowing you to customize your requests while maintaining a secure and automated workflow.

Prerequisites

Before you begin integration, you'll need:

1. API Endpoint: This is the URL to which your system will send data.

2. Client ID: A unique identifier for your application. It tells Vcheck which application is making the request and is required to initiate the OAuth2 authentication process.

3. Client Secret: A confidential key used along with the Client ID to securely verify your application's identity.

4. Scope: This defines the level of access your application is requesting (for example, read or write access to certain data). It helps control what your application is allowed to do once it’s authenticated.

5. Grant Type: Specifies the method your application will use to get an access token. For most cases, this will be "client_credentials", which means your application is requesting access on its own behalf rather than on behalf of a user.

To request these credentials, please contact our team at [e-mail]

Vcheck Platform's REST APIs use the OAuth2 framework for authentication and authorization. This industry-standard protocol allows applications to obtain secure, delegated access to API resources.

Before making API calls, your application must use its Client ID and Client Secret to request a temporary access token. This access token should then be included in the Authorization header of each API request as a Bearer token.

Each token is granted specific permissions, known as scopes, which define what actions the application is allowed to perform. If a request is made without a valid access token, the API will return an HTTP 401 Unauthorized response.

Authentication

Before you start using this API, you must authenticate using the OAuth2 Authentication API. This step is required to get an access token. Once you have the access token, you need to include it in the authorization header when calling the ID Verification Reports API. This ensures that only authorized users can access the reports.

POST:

https://api-platform.vcheckglobal.net/auth

HEADERS:

Content-Type: application/json

PAYLOAD:

We expect the payload to be in the following format:

{
   "grant_type": "client_credentials",
   "client_id": "string",
   “client_secret”: “string”,
   “scope”: “string”
}

RESPONSES:

SUCCESS (HTTP Status Code: 200)

{
    "access_token": "encoded string",
    “expires_in": 3600,
    “token_type": Bearer
}

ERROR (HTTP Status Code: 400)

• For missing required fields in the request payload

{
    "error": "invalid_request"
}

• For invalid client ID or secret

{
    "error": "invalid_client"
}

• For incorrect grant-type

{
    "error": "unsupported_grant_type"
}

Setup

Please configure your system to make a POST call to the given endpoint with the specified headers. Please make sure you choose and add the Products in the headers properly.

POST:

https://api-platform.vcheckglobal.net/investigation-request

HEADERS:

Authorization: <ACCESS_TOKEN>
Products: <PRODUCT_CODE>

PRODUCT CODES

Product Code	Service	Support
IDV	ID Verification	Supported
IDV_VIDEO	ID Verification with Video Recording	Supported
MONITORING	Continuous Monitoring	Supported

Sample Payloads

Field Requirements: We recommend that your payload contains at least these fields:

• name: Candidate’s full legal name

• email: Candidate’s email address

We support the structure in this format:

{
   "name": "string",
   "email": "[e-mail]"
}

Extended Example (with optional fields):

{
    "name": "Sarah Johnson",
    "email": "[e-mail]",
    "mobile_number": "[phone]",
    "address": "456 Oak Avenue, Suite 300, Metropolis, NY 10001, USA",
    "application_number": "1985-03-22",
    "department": "Sales and operations",
    "nationality": "US",
    "reference_id": "ABC-2023-0542"
}

Responses:

SUCCESS (HTTP Status Code: 201)

{
    "status": "201",
    "detail":
        {       
            "message": "Request submitted successfully."  
        }
}

ERROR (HTTP Status Code: 400)

{
    "status": "400",
    "detail":
        {       
            "message": "Invalid Payload."
        }
}

AUTHENTICATION ERROR (HTTP Status Code: 401)

{
    "status": "401",
    "detail":
        {       
            "message": " Unauthorized."
        }
}

RATE LIMIT (HTTP Status Code: 429)

We allow a maximum of 5 requests per second per API key. The API will return the error if the requests exceed that.

{
    "status": "429",
    "detail": 
        {       
            "message": " Too Many Requests.",   
        }
}

Greenhouse Integration (v1)

Overview

Enabling the automation of investigation requests for candidates directly from your Greenhouse system when you mark a candidate as "hired", this API streamlines the hiring process while ensuring compliance and security.

Prerequisites

Before setting up the integration, you'll need:

1. Administrator access to your Greenhouse account

2. Webhook URL (provided by Vcheck) /platform/api/v1/greenhouse/id-verification

3. Secret Key (provided by Vcheck)

To request these credentials, please contact our team at [e-mail] with the subject line "Greenhouse Integration Request".

Authentication Mechanism

This API uses Greenhouse’s signature authentication mechanism.

Setup

1. Log in to your Greenhouse account as an administrator

2. Click on the Configure icon on the top right

3. Navigate to Dev Center → Web Hooks

4. Click "Webhooks" and you will land on a “Create A New Webhook” page

5. Configure the webhook with the following details:

   1. Name: Give it a meaningful name, like vcheck-integration

   2. When: Choose: "hire_candidate"

   3. Endpoint URL: {webhook-url-provided-by-vcheck}

   4. Secret Key: {secret-key-provided-by-vcheck}

   5. Error recipient email: Add your email on which you wish to have notifications when an error occurs.

   6. Deactivated? Make sure it is set to No

6. Click on “Create Webhook”

On clicking “Create webhook”, your Greenhouse Recruiting will send a ping, prompting Vcheck to verify the connection's working. Once the ping is accepted successfully verified, the webhook will be created.

You can also refer to the Greenhouse documentation to setup a webhook here.

What Happens Next? When you mark a candidate as "hired" in your Greenhouse, the system automatically sends the candidate’s information to Vcheck for identity verification. You'll receive the verification results and the report directly in your Vcheck dashboard.

Requested Payload

Once the webhook is configured, we expect the Greenhouse webhook request will send the payload signature to be in the following format or at least contain these fields.

POST:

 https://portal-api.vcheckglobal.net/platform/api/v1/greenhouse/id-verification

BODY:

{
    "name": "string",
    "email": "[e-mail]",
    "dob": "string",
    "mobile_number": "string"
}

The exact fields may vary based on what information you collect in Greenhouse.

RATE LIMIT:

We allow a maximum of 5 requests per second per API key. Exceeding this, you will get a 419: Too many requests Error