CredTek API · v0

Integration Abstraction Layer · HTTP API

The IAL exposes one uniform interface for every external action CredTek triggers — whether the underlying work is an HTTP API call, a browser agent, or a human credentialing specialist. You call integrations.submit(), you get back an IntegrationJobwith a stable ID, status, and ETA. You poll or subscribe. You don't care which tier the integration falls into.

Base URL: https://www.cred-tek.com/api. All requests and responses are JSON. Demo endpoints use an in-memory store and are open (no auth). Production wires per-tenant JWT auth via Supabase + RLS.

Authentication

Production: Authorization: Bearer <jwt> header. JWTs are issued by Supabase Auth. Every request is tenant-scoped via the JWT claims; cross-tenant access returns 404 (not 403, to avoid resource-existence leaks).

Demo: no auth required. The mock store seeds 5 sample jobs under tenant_id="mindscape".

Integration tiers

Every external system CredTek interacts with falls into one of four tiers. From the API's perspective they look identical — same shape in, same shape out. The tier governs the lifecycle behavior under the hood.

tier_1_api — direct REST/GraphQL APIs (NPPES, OIG, SAM.gov, Checkr, Twilio, Resend). Synchronous or webhook-based.
tier_2_partner — gated APIs we access via an NCQA-certified CVO partner (CAQH ProView Credentialing API, NPDB queries).
tier_3_browser — web portals with no API. Playwright + LLM-assisted form fill. Always requires a human approval gate before submission.
tier_4_human— work that can't be automated in v1. Creates an Operations Queue ticket with an SLA-based ETA.

Lifecycle states

An IntegrationJob moves through a deterministic state machine (IAL §4). Transitions are the only place status changes; production enforces this with a database trigger.

draftedCreated, not yet submitted. Editable by the coordinator.

awaiting_approvalTier 3 only — agent has prepared submission, waiting on coordinator click.

submittedSent to external system or queued for ops specialist.

in_progressExternal system or specialist is actively working it.

awaiting_infoBlocked, waiting on provider or coordinator to supply additional info.

completedSuccessfully completed with structured result. Terminal.

failedPermanent failure, manual review required. Terminal.

cancelledCancelled by coordinator or admin. Terminal.

POST/api/integrations/submit

Create an IntegrationJob

Creates a new job in `drafted` state. Tier 3 jobs are auto-routed to `awaiting_approval` (human-in-the-loop gate per IAL §4). Tier 1/4 jobs can opt into immediate submission with `auto_submit: true`.

Request body

{
  "tenant_id": "mindscape",
  "integration_type": "optum_enrollment",
  "tier": "tier_3_browser",
  "provider_id": "james-mitchell",
  "payload": {
    "providerName": "James Mitchell",
    "credential": "LCSW",
    "state": "CA",
    "npi": "2109834567"
  },
  "auto_submit": false
}

Response

{
  "job": {
    "id": "job_01HZX7000000041F",
    "tenant_id": "mindscape",
    "integration_type": "optum_enrollment",
    "tier": "tier_3_browser",
    "provider_id": "james-mitchell",
    "status": "awaiting_approval",
    "payload": { ... },
    "result": null,
    "eta": "2026-05-12T15:30:00.000Z",
    "submitted_at": null,
    "completed_at": null,
    "created_by": "api_demo_user",
    "cost_cents": 0,
    "metadata": { "attempts": 0 },
    "audit_log_id": "audit_01HZX700000000",
    "created_at": "2026-04-29T15:30:00.000Z",
    "updated_at": "2026-04-29T15:30:00.000Z"
  }
}

Status codes

`201`	Created
`400`	missing_fields / invalid_tier / invalid_json

GET/api/integrations/list

List IntegrationJobs

Returns jobs filtered by query params. Newest first.

Query parameters

Name	Type	Description
`tenant_id`	`string`	Filter by customer org
`provider_id`	`string`	Filter by provider slug
`status`	`IntegrationStatus`	drafted \| awaiting_approval \| submitted \| in_progress \| awaiting_info \| completed \| failed \| cancelled
`limit`	`number`	Max rows. Default 50, capped 200.

Response

{
  "total": 5,
  "returned": 5,
  "limit": 50,
  "jobs": [
    { "id": "job_01HZX700000000A5", "status": "awaiting_info", ... },
    ...
  ]
}

Status codes

`200`	OK
`400`	invalid_status

GET/api/integrations/[id]

Fetch a single IntegrationJob

Returns the full job by ID.

Response

{
  "job": { "id": "job_01HZX700000000A1", "status": "drafted", ... }
}

Status codes

`200`	OK
`404`	not_found

POST/api/integrations/[id]

Apply a state transition

Drives the IAL state machine (§4). Validates the transition is legal for the current state and the actor type. Optional `patch` lets you update `result`, `eta`, `cost_cents`, or merge into `metadata` in the same call.

Request body

{
  "to_status": "submitted",
  "actor_type": "user",
  "patch": {
    "metadata": { "external_reference": "OPT-2026-04-CR-99812" }
  }
}

Response

{
  "job": { "id": "...", "status": "submitted", "submitted_at": "2026-04-29T15:31:00.000Z", ... }
}

Status codes

`200`	OK
`400`	missing_field / invalid_to_status / invalid_actor_type
`404`	job not found
`409`	job is in terminal state
`422`	transition_rejected (state machine refused)

Error response shape

All errors return a structured JSON body:

{
  "error": "transition_rejected",
  "reason": "no rule allows submitted → drafted",
  "message": "(optional human-readable hint)"
}

The error field is a stable machine-readable code; the reason / message are for humans and may change copy without breaking compatibility.

Ready to wire CredTek into your stack?

The same API your engineers see here is what runs in production. Tenant isolation via Supabase RLS, audit logging via the IAL §9 hash chain, and human-in-the-loop gates on every Tier 3 submission.

Book a 20-min demo →