> 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/api-reference/api-introduction.md). # API Introduction Onboarding, authentication, conventions and errors shared across the Vcheck API. ## Overview Vcheck Global provides a public system-to-system API that enables client platforms to integrate directly with Vcheck services. Through this API, clients can programmatically manage the complete lifecycle of every product on the platform: * **Monitoring** - enroll subjects for continuous screening, manage monitoring groups and participants, retrieve and action alerts, and control monitoring status. * **Background Check** - submit orders, track subjects, and retrieve structured reports and findings. * **ID Verification** - submit identity verification requests and retrieve verification reports. * **Common Endpoints** - look up products, subjects, and groups allotted to the account across all services in one place. Across every product, clients can place orders, manage subjects, receive real-time alerts and webhook notifications, and track results from a single, consistent API surface. This document serves as the authoritative integration guide for all clients. It covers registration, authentication and scopes, the complete OpenAPI contract for every product with request and response payloads, and outbound delivery mechanisms. ## Integration Flow The integration follows three sequential phases. Each phase must be completed before proceeding to the next. | Step | Action | Outcome | | ---- | ------------------------------------------------------------------------------------- | -------------------------------------------------- | | 1 | Vcheck onboards the client account | Account created in the platform | | 2 | Credentials issued (`client_id`, `client_secret`, scopes) | Client receives secure one-time credential package | | 3 | Webhook registered - only required if opting in to PUSH delivery. Not needed for PULL | Callback URL verified with test event | #### Credential Package | Value | Description | | --------------- | -------------------------------------------------------------------------------------------------------------- | | Client ID | Public identifier. Appears in logs, metering, and support tickets. Safe to share. | | Client Secret | Private credential. Must be stored in the client vault and kept confidential. | | Scopes | Space-separated permission list. Must be requested on every token call. | | Token URL | OAuth 2.0 client-credentials endpoint for bearer token exchange. | | Base URL | `https://api-platform.vcheckglobal.net` (sandbox host issued first; production host after sign-off) | | Acknowledgement | Account-level setting for whether delivery acknowledgements are sent. On by default; contact Vcheck to change. | #### Scopes | Scope | Name | Direction | Description | | ----------------------------------------- | --------------------------- | -------------------- | ---------------------------------------------------- | | `api-platform/monitoring-read` | Monitoring Read | Outbound | Read-only access to monitoring endpoints. | | `api-platform/monitoring-read-write` | Monitoring Read Write | Inbound and Outbound | Read and write access to monitoring endpoints. | | `api-platform/backgroundcheck-read` | Background Check Read | Outbound | Read access to background check endpoints. | | `api-platform/backgroundcheck-read-write` | Background Check Read Write | Inbound and Outbound | Read and write access to background check endpoints. | #### Registering a Webhook By default, every client is already set up for PULL - no registration is required, and the polling endpoints are available as soon as credentials are issued. PUSH delivery is optional: a client who wants results pushed to their own endpoint can register a webhook using the details below, or contact their Vcheck account representative, who will do the needful to configure it on their behalf. **What Vcheck needs from the client to register a webhook** | Item | Notes | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Webhook URL (Callback URL) | HTTPS endpoint that receives deliveries. Must return 2xx on a test delivery | | Throttle Configuration | Preferred max events/second | | Throttle Delay | Pause between delivery batches if the client endpoint returns an error status; delivery resumes automatically once the delay elapses | | Authentication Method | HMAC-SHA256, Bearer Token, or Header API Key | | Webhook Secret | Provided by the client | **Webhook registration and maintenance** | Operation | Description | | ---------------------- | -------------------------------------------------------------------------------------------------- | | Register Webhook URL | Provide the HTTPS endpoint during onboarding, or at any later point; verified with a test delivery | | Renewal of Webhook URL | Update the webhook URL at any time | | Runtime Update | Webhook URL changes take effect immediately, as soon as they are saved; no downtime | | Step | Action | Outcome | | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | | 4 | Client authenticates via OAuth 2.0 (`POST /v2/oauth2/token`) | Bearer token received (valid 1 hour) | | 5 | Client includes the bearer token on every inbound request to call the API - discovering products, subjects, and groups, placing orders, and tracking their status | Valid response for each call | Results can be retrieved two ways - the client pulls on demand, or Vcheck pushes to a registered webhook as soon as an alert is generated. Both read from the same event store, and a client may use either or both. #### Outbound - Pull | Step | Action | Outcome | | ---- | -------------------------------------------------------------------------------------- | --------------------------------- | | 6 | Client retrieves alerts via `GET /v2/monitoring/alerts`, at any time of their choosing | Client retrieves alerts on demand | #### Outbound - Push Applies only to clients who have registered a webhook - see Registering a Webhook. Delivery is subject to the Throttle Delay and Throttle Configuration (requests per second) agreed at registration. | Step | Action | Outcome | | ---- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | 7 | An alert is generated for a monitored subject | Alert queued for delivery | | 8 | Vcheck delivers the alert to the client's registered callback URL, at the configured requests-per-second rate | Delivery paused and retried per the Throttle Delay if the client endpoint returns an error status | ## Conventions | Aspect | Convention | | ------------------ | ----------------------------------------------------------------------- | | Base URL | `https://api-platform.vcheckglobal.net` | | Transport | HTTPS only, TLS 1.2+. Plain HTTP refused, not redirected | | Content Type | `application/json`, UTF-8 (token endpoint is form-encoded) | | Naming | `snake_case` throughout | | Dates | ISO 8601; timestamps in UTC with explicit offset | | Nulls | Absent and `null` are equivalent. Empty string is not null | | Unknown Properties | Rejected, not ignored. Misspelled properties are never silently dropped | | Pagination | Cursor-based. Default and max page: 50 | | Versioning | Major version in path. Additive changes do not bump version | #### Request Headers | Header | Required | Purpose | | -------------------------------- | ----------------------- | ----------------------------- | | `Authorization: Bearer ` | Every call except token | Token from OAuth 2.0 exchange | | `Content-Type: application/json` | POST and PATCH | Body media type | Export endpoints are the exception - see the specific endpoint (e.g. `POST /monitoring/alerts/export`) for its required `Accept` header, used to receive the exported file as a binary download instead of base64-encoded text. #### Standard Error Format Every error uses the same JSON structure. Branch on `code`, never on `message`. ```json { "error": { "code": "PRODUCT_NOT_ALLOTTED", "message": "The product 'Criminal Monitoring' is not allotted to this account.", "request_id": "3f9c1a7e-25b8-4a01-9a6c-9a3f2b5d1e77" } } ``` #### Pagination Pass the `next` page URL or cursor for the following page. Stop when `next` is `null`. ## Error Codes | Code | Meaning | Action | | ----------------------- | ----------------------------- | ----------------------------- | | `SCHEMA_INVALID` | Body failed request model | Fix payload; do not retry | | `FIELD_INVALID` | Field failed business rule | Correct named field | | `TOKEN_INVALID` | Missing, expired or bad token | Re-authenticate | | `CLIENT_NOT_REGISTERED` | Valid token, unknown client | Contact Vcheck | | `SCOPE_MISSING` | Token lacks required scope | Request scope through Vcheck | | `PRODUCT_NOT_ALLOTTED` | Product not on the account | Contact Client Success | | `NOT_FOUND` | Does not exist or not owned | Verify via discovery endpoint | | `DUPLICATE_REQUEST` | Matching request in flight | Use the returned ID | | `INTERNAL_ERROR` | Unhandled platform fault | Retry the request | ## Support For onboarding and integration assistance: **Customer Success:** When contacting support, include your Client ID. --- # 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/api-reference/api-introduction.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.