Skip to content

API

Overview

Authentication, resource model, errors, and versioning for the FinCheckers HTTP API.

  • API
  • 1 min read

Base URL and versioning

{FINCHECKERS_API_BASE_URL}/v1

The path segment v1 is the public API major. Breaking changes ship under a new major; additive fields may appear within a major. Check Release notes before upgrading clients.

Authentication

Send a bearer token on every request:

Authorization: Bearer <token>
X-FinCheckers-Tenant-Id: <tenant-id>

Tokens are scoped (cases:read, cases:write, cases:review, admin:types, …). Missing scopes return 403 with the required scope name in the error body.

Core resources

| Resource | Path | Notes | | --------- | ---------------------- | ------------------------------------------- | | Cases | /cases | Create, get, list, process, review, archive | | Documents | /cases/:id/documents | Attach and list documents under a case | | Auth | /auth/whoami | Token and tenant verification | | Types | /admin/types | Admin configuration of verification types |

List endpoints are cursor-paginated. Include query include=findings,review,history (or repeated include[]) when decision context is required.

Errors

Responses use a common envelope:

{
  "error": {
    "code": "invalid_transition",
    "message": "Status 'completed' is not allowed from 'intake'",
    "details": { "allowed": ["processing", "ready_for_review"] }
  }
}

| HTTP | Typical meaning | | ----- | ------------------------------------------------ | | 400 | Validation failure | | 401 | Missing or invalid token | | 403 | Insufficient scope | | 404 | Unknown resource | | 409 | Conflict (invalid transition, concurrent update) | | 429 | Rate limited |

SDKs

The TypeScript SDK wraps these resources. See Installation and Quick start. For rollout sequencing: Implementation guide.

Related