> 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/monitoring/monitoring-orders.md). # Monitoring Orders Place monitoring orders and track request status. ## Place Monitoring Order > Places a bulk monitoring order. The body is an object containing a \`group\_details\` array. Each element represents one group and carries its own subjects split into individuals and entities.\ > \ > \*\*Bulk limits:\*\*\ > \ > \| Element | Limit | Behaviour |\ > \|---|---|---|\ > \| Groups per request | 10 | FIELD\_INVALID - request refused |\ > \| Subjects per group | 1000 | FIELD\_INVALID - request refused |\ > \| Products per subject | 1+ | PRODUCT\_NOT\_ALLOTTED |\ > \ > \*\*Group rules:\*\*\ > \ > \| Scenario | Required | Result |\ > \|---|---|---|\ > \| New group | \`group\_name\` only (id omitted or null) | New group created, subjects added |\ > \| Existing group | \`id\` (group ID) only | Subjects added to existing group |\ > \ > \- \`monitoring\_end\_date\` - optional ISO 8601 date; null = indefinite.\ > \- \`participants\` - email addresses of project participants.\ > \ > \*\*Subject rules:\*\*\ > \ > \| Scenario | Required |\ > \|---|---|\ > \| New individual | \`first\_name\`, \`last\_name\`, \`products\` |\ > \| Existing individual | \`id\` (subject ID) |\ > \| New entity | \`last\_name\_entity\`, \`products\` |\ > \| Existing entity | \`id\` (subject ID) |\ > \ > \- \`date\_of\_birth\` format: MM/DD/YYYY.\ > \- \`alternate\_name\` - name in foreign characters for multi-language coverage.\ > \- \`refinements\` - optional keyword hints to sharpen match accuracy.\ > \- \`company\_name\` - optional company association for individuals.\ > \ > \*\*Per-subject tracking:\*\*\ > \- Each subject receives its own \`request\_id\` for status polling.\ > \- Poll \`GET /v2/monitoring/request/{request\_id}/\` with any \`request\_id\`.\ > \- The \`full\_payload\_request\_id\` tracks the overall bulk request.\ > \ > \*\*Other notes:\*\*\ > \- Groups are committed independently - a failing group appears in \`groups\_failed\`.\ > \- Groups are committed independently, so a retry is safe as long as you check \`groups\_failed\` in the response.\ > \ > \### Response fields\ > \ > \| Field | Type | Description |\ > \|-------|------|-------------|\ > \| \`full\_payload\_request\_id\` | string (UUID) | Overall bulk request tracking ID |\ > \| \`message\` | string | Human-readable status message |\ > \| \`total\_groups\` | integer | Number of groups accepted |\ > \| \`total\_subjects\` | integer | Total subjects accepted across all groups |\ > \| \`groups\` | array\[object] | Groups that were accepted for processing |\ > \| \`groups\_failed\` | array\[object] | Groups that failed during processing |\ > \| \`status\_url\` | string | URL to poll for overall bulk request status |\ > \ > \### Groups object fields\ > \ > \| Field | Type | Description |\ > \|-------|------|-------------|\ > \| \`group\_id\` | integer | Group ID |\ > \| \`name\` | string | Group name |\ > \| \`subjects\_accepted\` | integer | Number of subjects accepted in this group |\ > \| \`subject\_request\_ids\` | array\[object] | Per-subject request IDs for status polling |\ > \ > \### Subject request ID fields\ > \ > \| Field | Type | Description |\ > \|-------|------|-------------|\ > \| \`subject\_id\` | integer | Subject ID (null for new subjects) |\ > \| \`subject\_name\` | string | Subject display name |\ > \| \`subject\_type\` | string | \`individual\` or \`entity\` |\ > \| \`request\_id\` | string (UUID) | Per-subject request ID for individual status polling |\ > \ > \### Groups failed object fields\ > \ > \| Field | Type | Description |\ > \|-------|------|-------------|\ > \| \`group\_name\` | string | Group name |\ > \| \`id\` | integer | Group ID |\ > \| \`failed\_at\_handler\` | string | Processing step where failure occurred |\ > \| \`failure\_error\` | string | Error detail |\ > \ > \### Example Request\ > \ > \`\`\`json\ > {\ > "group\_details": \[\ > {\ > "group\_name": "Q3 Onboarding - EMEA",\ > "monitoring\_end\_date": null,\ > "participants": \[""],\ > "subjects": {\ > "individuals": \[\ > {\ > "first\_name": "John",\ > "last\_name": "Doe",\ > "date\_of\_birth": "01/15/1985",\ > "company\_name": "Doe Industries",\ > "alternate\_name": "",\ > "refinements": \["CEO", "New York"],\ > "products": \[{"id": 1, "name": "Global Watchlist"}]\ > }\ > ],\ > "entities": \[]\ > }\ > },\ > {\ > "group\_name": "Background Check - APAC",\ > "subjects": {\ > "individuals": \[\ > {\ > "first\_name": "Jane",\ > "last\_name": "Smith",\ > "products": \[{"id": 1, "name": "Global Watchlist"}]\ > }\ > ],\ > "entities": \[\ > {\ > "last\_name\_entity": "Acme Corp",\ > "refinements": \["Delaware"],\ > "products": \[{"id": 1, "name": "Global Watchlist"}]\ > }\ > ]\ > }\ > }\ > ]\ > }\ > \`\`\`
````json {"openapi":"3.1.0","info":{"title":"Vcheck Global API","version":"5.4.0"},"tags":[{"name":"Monitoring Orders","description":"Place monitoring orders and track request status."}],"servers":[{"url":"https://api-platform.vcheckglobal.net/v2","description":"Vcheck platform (sandbox host issued first; production host after sign-off)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Obtain a token via POST https://api-platform.vcheckglobal.net/v2/oauth2/token.\nInclude in all subsequent requests as `Authorization: Bearer `.\nTokens expire after 3,600 seconds - cache and reuse; request a new one only when close to expiry.\n"}}},"paths":{"/monitoring/request":{"post":{"tags":["Monitoring Orders"],"operationId":"placeMonitoringOrder","summary":"Place Monitoring Order","description":"Places a bulk monitoring order. The body is an object containing a `group_details` array. Each element represents one group and carries its own subjects split into individuals and entities.\n\n**Bulk limits:**\n\n| Element | Limit | Behaviour |\n|---|---|---|\n| Groups per request | 10 | FIELD_INVALID - request refused |\n| Subjects per group | 1000 | FIELD_INVALID - request refused |\n| Products per subject | 1+ | PRODUCT_NOT_ALLOTTED |\n\n**Group rules:**\n\n| Scenario | Required | Result |\n|---|---|---|\n| New group | `group_name` only (id omitted or null) | New group created, subjects added |\n| Existing group | `id` (group ID) only | Subjects added to existing group |\n\n- `monitoring_end_date` - optional ISO 8601 date; null = indefinite.\n- `participants` - email addresses of project participants.\n\n**Subject rules:**\n\n| Scenario | Required |\n|---|---|\n| New individual | `first_name`, `last_name`, `products` |\n| Existing individual | `id` (subject ID) |\n| New entity | `last_name_entity`, `products` |\n| Existing entity | `id` (subject ID) |\n\n- `date_of_birth` format: MM/DD/YYYY.\n- `alternate_name` - name in foreign characters for multi-language coverage.\n- `refinements` - optional keyword hints to sharpen match accuracy.\n- `company_name` - optional company association for individuals.\n\n**Per-subject tracking:**\n- Each subject receives its own `request_id` for status polling.\n- Poll `GET /v2/monitoring/request/{request_id}/` with any `request_id`.\n- The `full_payload_request_id` tracks the overall bulk request.\n\n**Other notes:**\n- Groups are committed independently - a failing group appears in `groups_failed`.\n- Groups are committed independently, so a retry is safe as long as you check `groups_failed` in the response.\n\n### Response fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `full_payload_request_id` | string (UUID) | Overall bulk request tracking ID |\n| `message` | string | Human-readable status message |\n| `total_groups` | integer | Number of groups accepted |\n| `total_subjects` | integer | Total subjects accepted across all groups |\n| `groups` | array[object] | Groups that were accepted for processing |\n| `groups_failed` | array[object] | Groups that failed during processing |\n| `status_url` | string | URL to poll for overall bulk request status |\n\n### Groups object fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `group_id` | integer | Group ID |\n| `name` | string | Group name |\n| `subjects_accepted` | integer | Number of subjects accepted in this group |\n| `subject_request_ids` | array[object] | Per-subject request IDs for status polling |\n\n### Subject request ID fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `subject_id` | integer | Subject ID (null for new subjects) |\n| `subject_name` | string | Subject display name |\n| `subject_type` | string | `individual` or `entity` |\n| `request_id` | string (UUID) | Per-subject request ID for individual status polling |\n\n### Groups failed object fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `group_name` | string | Group name |\n| `id` | integer | Group ID |\n| `failed_at_handler` | string | Processing step where failure occurred |\n| `failure_error` | string | Error detail |\n\n### Example Request\n\n```json\n{\n \"group_details\": [\n {\n \"group_name\": \"Q3 Onboarding - EMEA\",\n \"monitoring_end_date\": null,\n \"participants\": [\"analyst@example.com\"],\n \"subjects\": {\n \"individuals\": [\n {\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"01/15/1985\",\n \"company_name\": \"Doe Industries\",\n \"alternate_name\": \"\",\n \"refinements\": [\"CEO\", \"New York\"],\n \"products\": [{\"id\": 1, \"name\": \"Global Watchlist\"}]\n }\n ],\n \"entities\": []\n }\n },\n {\n \"group_name\": \"Background Check - APAC\",\n \"subjects\": {\n \"individuals\": [\n {\n \"first_name\": \"Jane\",\n \"last_name\": \"Smith\",\n \"products\": [{\"id\": 1, \"name\": \"Global Watchlist\"}]\n }\n ],\n \"entities\": [\n {\n \"last_name_entity\": \"Acme Corp\",\n \"refinements\": [\"Delaware\"],\n \"products\": [{\"id\": 1, \"name\": \"Global Watchlist\"}]\n }\n ]\n }\n }\n ]\n}\n```\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"required":["group_details"],"type":"object","properties":{"group_details":{"description":"Array of group objects. Maximum 10 per request.","type":"array","items":{"description":"**New group:** `group_name` required (id omitted or null).\n**Existing group:** `id` required (group_name optional).","required":["subjects"],"type":"object","properties":{"id":{"description":"Omit or null to create a new group; the group ID to add subjects to an existing group.","type":["integer","null"]},"group_name":{"description":"Name of the group. Required for new groups; optional for existing.","type":"string"},"monitoring_end_date":{"description":"Optional date to stop monitoring. null means indefinite.","type":["string","null"],"format":"date"},"participants":{"description":"Email addresses of project participants for this group.","type":"array","items":{"type":"string","format":"email"}},"subjects":{"description":"At least one individual or entity must be present per group.","type":"object","properties":{"individuals":{"description":"Individual subjects to enrol. Maximum 1000 combined with entities.","type":"array","items":{"description":"**New individual:** `first_name`, `last_name`, `products` required.\n**Existing individual:** `id` only (all other fields optional).","type":"object","properties":{"id":{"description":"Omit or null for a new subject; the subject ID for an existing subject.","type":["integer","null"]},"first_name":{"description":"Required for new individuals.","type":"string"},"last_name":{"description":"Required for new individuals.","type":"string"},"date_of_birth":{"description":"Format MM/DD/YYYY.","type":"string"},"company_name":{"description":"Optional company association for individuals.","type":"string"},"alternate_name":{"description":"Name in foreign characters for multi-language coverage.","type":"string"},"refinements":{"description":"Optional keyword hints to sharpen match accuracy.","type":"array","items":{"type":"string"}},"products":{"description":"Products to enrol this subject in. Required for new subjects; optional for existing.","type":"array","items":{"required":["id"],"type":"object","properties":{"id":{"description":"Product ID (required).","type":"integer"},"name":{"description":"Product name (optional).","type":"string"}}}}}}},"entities":{"description":"Entity subjects to enrol. Maximum 1000 combined with individuals.","type":"array","items":{"description":"**New entity:** `last_name_entity`, `products` required.\n**Existing entity:** `id` only (all other fields optional).","type":"object","properties":{"id":{"description":"Omit or null for a new entity; the subject ID for an existing entity.","type":["integer","null"]},"last_name_entity":{"description":"Required for new entities.","type":"string"},"alternate_name":{"description":"Name in foreign characters for multi-language coverage.","type":"string"},"refinements":{"description":"Optional keyword hints to sharpen match accuracy.","type":"array","items":{"type":"string"}},"products":{"description":"Products to enrol this entity in. Required for new entities; optional for existing.","type":"array","items":{"required":["id"],"type":"object","properties":{"id":{"description":"Product ID (required).","type":"integer"},"name":{"description":"Product name (optional).","type":"string"}}}}}}}}}}}}}}}}},"responses":{"200":{"description":"Order accepted. Background processing queued.","content":{"application/json":{"schema":{"type":"object","properties":{"full_payload_request_id":{"description":"Request ID for the overall bulk request. Poll this for bulk status.","type":"string","format":"uuid"},"message":{"description":"Human-readable status message.","type":"string"},"total_groups":{"description":"Number of groups accepted.","type":"integer"},"total_subjects":{"description":"Total number of subjects accepted across all groups.","type":"integer"},"groups":{"description":"Groups that were accepted for processing.","type":"array","items":{"type":"object","properties":{"group_id":{"description":"Group ID.","type":["integer","null"]},"name":{"description":"Group name.","type":"string"},"subjects_accepted":{"description":"Number of subjects accepted in this group.","type":"integer"},"subject_request_ids":{"description":"Per-subject request IDs for individual status polling.","type":"array","items":{"type":"object","properties":{"subject_id":{"description":"Subject ID. null for new subjects.","type":["integer","null"]},"subject_name":{"description":"Subject display name.","type":"string"},"subject_type":{"description":"'individual' or 'entity'.","type":"string","enum":["individual","entity"]},"request_id":{"description":"Per-subject request ID for individual status polling.","type":"string","format":"uuid"}}}}}}},"groups_failed":{"description":"Groups that failed during processing.","type":"array","items":{"type":"object","properties":{"group_name":{"description":"Group name.","type":"string"},"id":{"description":"Group ID.","type":["integer","null"]},"failed_at_handler":{"description":"Processing step where failure occurred.","type":["string","null"]},"failure_error":{"description":"Error detail.","type":["string","null"]}}}},"status_url":{"description":"URL to poll for the overall bulk request status.","type":"string"}}}}}},"400":{"description":"The request was rejected before processing. Possible error codes:\n\n| Code | Trigger |\n|---|---|\n| SCHEMA_INVALID | group_details missing, wrong type, or body is not valid JSON |\n| FIELD_INVALID | More than 10 groups |\n| FIELD_INVALID | More than 1000 subjects (individuals + entities) in a group |\n| FIELD_INVALID | group_name missing for a new group |\n| FIELD_INVALID | first_name or last_name missing for a new individual |\n| FIELD_INVALID | last_name_entity missing for a new entity |\n| FIELD_INVALID | products array missing or empty on a new subject |\n| PRODUCT_NOT_ALLOTTED | A product ID is not enabled on this account |\n| GROUP_NOT_FOUND | A group ID does not belong to this account |\n| SUBJECT_NOT_FOUND | A subject ID does not belong to this account |","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}},"403":{"description":"Forbidden - missing or invalid Client-ID credentials, insufficient scope, endpoint disabled via feature flag, or authenticated client has no linked account. Verify the scopes assigned to your credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"description":"Authorization or access error message.","type":"string","default":"This endpoint is currently disabled."}}}}}},"500":{"description":"Internal server error - an unexpected error occurred. Please try again later or contact support if the issue persists.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"description":"Internal server error message.","type":"string","default":"An unexpected error occurred while processing the request."}}}}}}}}}}} ```` ## Track Request Status > Returns the tracked status of a previously submitted monitoring order request. The \`request\_id\` is returned in the response when the order is placed.\ > \ > Works for both \`full\_payload\_request\_id\` (overall bulk request) and per-subject \`request\_id\` (individual subject processing).\ > \ > \### Possible statuses\ > \ > \| Status | Meaning |\ > \|--------|-------------|\ > \| \`QUEUED\` | Received, waiting to process |\ > \| \`PROCESSING\` | Subjects/groups being created |\ > \| \`COMPLETED\` | All groups processed |\ > \| \`FAILED\` | Processing failed; check \`groups\_failed\` for details |\ > \ > \### Response fields\ > \ > \| Field | Type | Description |\ > \|-------|------|-------------|\ > \| \`request\_id\` | string (UUID) | The request tracking ID that was polled |\ > \| \`status\` | string | Current processing status (see table above) |\ > \| \`http\_method\` | string | HTTP method of the original request |\ > \| \`submitted\_on\` | string (ISO 8601) | When the request was received |
```json {"openapi":"3.1.0","info":{"title":"Vcheck Global API","version":"5.4.0"},"tags":[{"name":"Monitoring Orders","description":"Place monitoring orders and track request status."}],"servers":[{"url":"https://api-platform.vcheckglobal.net/v2","description":"Vcheck platform (sandbox host issued first; production host after sign-off)"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Obtain a token via POST https://api-platform.vcheckglobal.net/v2/oauth2/token.\nInclude in all subsequent requests as `Authorization: Bearer `.\nTokens expire after 3,600 seconds - cache and reuse; request a new one only when close to expiry.\n"}}},"paths":{"/monitoring/request/{request_id}":{"get":{"tags":["Monitoring Orders"],"operationId":"pollMonitoringOrderStatus","summary":"Track Request Status","description":"Returns the tracked status of a previously submitted monitoring order request. The `request_id` is returned in the response when the order is placed.\n\nWorks for both `full_payload_request_id` (overall bulk request) and per-subject `request_id` (individual subject processing).\n\n### Possible statuses\n\n| Status | Meaning |\n|--------|-------------|\n| `QUEUED` | Received, waiting to process |\n| `PROCESSING` | Subjects/groups being created |\n| `COMPLETED` | All groups processed |\n| `FAILED` | Processing failed; check `groups_failed` for details |\n\n### Response fields\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `request_id` | string (UUID) | The request tracking ID that was polled |\n| `status` | string | Current processing status (see table above) |\n| `http_method` | string | HTTP method of the original request |\n| `submitted_on` | string (ISO 8601) | When the request was received |\n","parameters":[{"name":"request_id","in":"path","required":true,"description":"The request_id returned when the order was placed.","schema":{"type":"string"}}],"responses":{"200":{"description":"Status retrieved successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"request_id":{"type":"string","format":"uuid"},"status":{"description":"QUEUED, IN_PROGRESS, COMPLETED, or FAILED.","type":"string","enum":["RECEIVED","PROCESSING","QUEUED","COMPLETED","FAILED","SUSPENDED"]},"http_method":{"type":"string"},"submitted_on":{"type":"string","format":"date-time"}}}}}},"403":{"description":"Forbidden - missing or invalid Client-ID credentials, insufficient scope, endpoint disabled via feature flag, or authenticated client has no linked account. Verify the scopes assigned to your credentials.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"description":"Authorization or access error message.","type":"string","default":"This endpoint is currently disabled."}}}}}},"404":{"description":"No request found for this request_id.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"500":{"description":"Internal server error - an unexpected error occurred. Please try again later or contact support if the issue persists.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"description":"Internal server error message.","type":"string","default":"An unexpected error occurred while processing the request."}}}}}}}}}}} ``` --- # 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/monitoring/monitoring-orders.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.