# VeroFlag Public API Agent Brief Use this brief when you are an AI agent integrating with VeroFlag from a trusted server-side runtime. ## Boundaries - Never expose a VeroFlag API key in browser or mobile code. - Treat your API key as your actor identity. Actions are audited. - Use idempotency keys on every mutation. - Reuse an idempotency key only for the exact same method, path, and body. - Do not record final case decisions with an agent key. Agent keys are blocked from that action in the MVP. - Escalate uncertainty to a human reviewer instead of inventing a conclusion. - A failed check is not the same as no matches. ## Main Flow 1. Call `GET /api/v1/groups` to identify visible groups. 2. Call `POST /api/v1/cases` to create or reuse a subject, create a case, and queue checks. 3. Poll `GET /api/v1/cases/{case_reference}` or use webhooks until checks complete. 4. Use `GET /api/v1/checks/{check_reference}` for detailed match evidence. 5. Use `GET /api/v1/cases/{case_reference}/events` to read case activity without scraping the UI. 6. If allowed by policy, call `PATCH /api/v1/matches/{match_id}/review` to mark matches as `confirmed_match`, `not_relevant`, or `pending_review`. 7. Add escalation context with `POST /api/v1/cases/{case_reference}/materials`. 8. Enroll ongoing subject monitoring with `POST /api/v1/monitoring-configs` only when your workflow explicitly needs daily PEP, sanctions, or business-entity-risk monitoring. 9. Leave the case decision pending for a human or explicitly permitted API client. ## Case Activity Use case events to understand what happened before your agent acts. ```http GET /api/v1/cases/{case_reference}/events?limit=25 Authorization: Bearer vf_live_... ``` Events are returned newest first with an opaque `next_cursor` for pagination. VeroFlag exposes allowlisted case workflow events only; workspace-wide internal audit logs are not exposed through this first API slice. ## Case Materials Use case materials for notes and links that help a reviewer understand what happened. ```http POST /api/v1/cases/{case_reference}/materials Authorization: Bearer vf_live_... Idempotency-Key: material- Content-Type: application/json ``` ```json { "title": "Agent escalation note", "note": "I found two possible matches and cannot resolve the identity with available evidence.", "url": "https://example.com/supporting-context" } ``` The request must include `title` and at least one of `note` or `url`. Binary files are not supported by the public API yet. ## Check And Match Review Read a check before reviewing matches: ```http GET /api/v1/checks/{check_reference} Authorization: Bearer vf_live_... ``` If your policy allows automated match review, only use the explicit review states: ```http PATCH /api/v1/matches/{match_id}/review Authorization: Bearer vf_live_... Idempotency-Key: match-review- Content-Type: application/json ``` ```json { "review_status": "not_relevant", "note": "Different date of birth." } ``` Do not mark more than one genuinely distinct person or business as confirmed for the same check. If ambiguity remains, add a material note and leave the check pending for a human. ## Monitoring Monitoring is subject-centric. Use an existing `subject_reference`; do not create duplicate cases only to turn on monitoring. ```http POST /api/v1/monitoring-configs Authorization: Bearer vf_live_... Idempotency-Key: monitoring- Content-Type: application/json ``` ```json { "subject_reference": "SRI502707", "check_types": ["pep", "sanctions"], "status": "active" } ``` Read the configuration, runs, and alerts through: - `GET /api/v1/monitoring-configs` - `GET /api/v1/monitoring-configs/{monitoring_config_id}` - `GET /api/v1/monitoring-configs/{monitoring_config_id}/runs` - `GET /api/v1/monitoring-configs/{monitoring_config_id}/alerts` New actionable matches may create a normal follow-up case. Changed known matches produce alerts with `recommended_next_actions`; review the alert before creating additional work. ## Webhooks Prefer webhooks over tight polling once an integration is in production. Verify every delivery before acting. - Signature base string: `.` - Signature header: `VeroFlag-Signature`, with `v1=` - HMAC key: the signing secret shown once when the endpoint is created or rotated. - Timestamp header: `VeroFlag-Timestamp` - Reject payloads older than five minutes. - Store processed `VeroFlag-Event-Id` values so duplicate deliveries are safe. - Summary payloads include `account_id`, `group_id`, and `object`. - Expanded payloads add event-specific fields such as `case_reference`, `check_reference`, `match_id`, `decision`, `monitoring_config_id`, or `alert_id`. Webhook delivery is at least once and retried durably, so your handler must be idempotent. ## Errors Common error codes: - `unauthorized`: missing, invalid, revoked, or expired API key. - `forbidden`: valid key, but missing scope, group access, or actor permission. - `invalid_request`: malformed JSON, query, path, or missing required header. - `idempotency_conflict`: same idempotency key reused with a different request. - `conflict`: duplicate or in-progress mutation conflict. - `not_found`: object missing or outside the key scope. - `unprocessable_entity`: valid JSON but a business rule failed. - `rate_limited`: back off and retry with jitter. - `internal_error`: retry safely; share `request_id` with support if persistent. Error envelope: ```json { "error": { "code": "invalid_request", "message": "Case creation request is invalid.", "details": {} }, "meta": { "request_id": "req_..." } } ``` ## Decision Hints - `requires_human_review: true` means do not auto-clear the case. - `recommended_next_actions` is the safest next-step list for automation. - A failed check is not the same as no matches. - `no_matches_found` can be system-set for a check, but the final case decision remains human controlled unless a trusted API client has explicit final-decision permission. ## Useful Docs - OpenAPI JSON: https://veroflag.com/docs/api/openapi.json - API docs: https://veroflag.com/docs/api