> For the complete documentation index, see [llms.txt](https://docs.vcheckglobal.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vcheckglobal.com/products/id-verification/api/api-reference-v1.md). # API Reference (v1) Request and response details for the ID Verification API v1. ## 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 {% hint style="info" %} 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. {% endhint %} ### 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:** ```url https://api-platform.vcheckglobal.net/auth ``` **HEADERS:** ``` Content-Type: application/json ``` **PAYLOAD:** We expect the payload to be in the following format: ```json { "grant_type": "client_credentials", "client_id": "string", “client_secret”: “string”, “scope”: “string” } ``` **RESPONSES:** SUCCESS (HTTP Status Code: 200) ```json { "access_token": "encoded string", “expires_in": 3600, “token_type": Bearer } ``` ERROR (HTTP Status Code: 400)\ * *For missing required fields in the request payload* ```json { "error": "invalid_request" } ``` * *For invalid client ID or secret* ```json { "error": "invalid_client" } ``` * *For incorrect grant-type* ```json { "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:** ```url https://api-platform.vcheckglobal.net/investigation-request ``` #### **HEADERS:** ```powershell Authorization: Products: ``` #### **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: ```json { "name": "string", "email": "user@example.com" } ``` Extended Example (with optional fields): ```json { "name": "Sarah Johnson", "email": "sarah.johnson@example.com", "mobile_number": "+12025550146", "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) ```json { "status": "201", "detail": { "message": "Request submitted successfully." } } ``` **ERROR** (HTTP Status Code: 400) ```json { "status": "400", "detail": { "message": "Invalid Payload." } } ``` **AUTHENTICATION ERROR** (HTTP Status Code: 401) ```json { "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. ```json { "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 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. {% hint style="info" %} You can also refer to the Greenhouse documentation to setup a webhook [here](https://support.greenhouse.io/hc/en-us/articles/360005574531-Create-a-webhook). {% endhint %} **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:** ```url https://portal-api.vcheckglobal.net/platform/api/v1/greenhouse/id-verification ``` **BODY:** ```json { "name": "string", "email": "user@example.com", "dob": "string", "mobile_number": "string" } ``` {% hint style="info" %} The exact fields may vary based on what information you collect in Greenhouse. {% endhint %} **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` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.vcheckglobal.com/products/id-verification/api/api-reference-v1.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.