Skip to main content
Koshio

developers

An API designed to be integrated once

How the Koshio APIs are designed, taken from the draft API contract. Detailed documentation is shared during onboarding.

Book a demo

by design

How the API is designed

  • One route per check

    Each check has its own typed operation and schema, so your client knows exactly what it can send.

    POST /v1/capabilities/{check}/requests

  • Purpose and consent in every request

    Every request names an approved purpose and carries a consent record wherever the source or your policy needs one.

    context.purpose · context.consentArtifact

  • One response shape

    Every check answers with the same envelope: a status, the result, its quality, any policy assessment and references to the evidence behind it.

    status · result · quality · assessment · evidenceReferences

  • Safe retries

    Every create carries an idempotency key, so a retry after a timeout never runs a check twice or charges for it twice.

    Idempotency-Key

  • Errors you can act on

    Errors follow RFC 9457 problem details, with a stable code, whether a retry may help, and the request and trace IDs to quote.

    application/problem+json

  • Longer checks without holding a connection

    Checks that take longer are accepted straight away and can be read back by request ID when they finish.

    GET /v1/requests/{requestId}

  • Short-lived credentials

    Calls use short-lived tokens from OAuth client credentials or mutual TLS, scoped to one customer and environment.

    Authorization: Bearer …

sample

A request, end to end

From the draft contract, filled with synthetic values. Fields may change before release.

Check a PANSample · synthetic data

POST /v1/capabilities/pan-verification-status/requests

Request

{
  "context": {
    "groupId": "SYNTHETIC-GROUP-001",
    "purpose": "SYNTHETIC-PURPOSE-ONBOARDING",
    "testDataMarker": "SYNTHETIC_TEST_DATA"
  },
  "input": {
    "pan": "SYNTHETIC-PAN-NOT-FOR-LIVE-USE"
  }
}

Response

{
  "requestId": "SYNTHETIC-REQUEST-0001",
  "status": "completed",
  "capability": "pan-verification-status",
  "capabilityVersion": "SYNTHETIC-2026-10",
  "result": {
    "registryStatus": "active",
    "attributes": {
      "nameOnRecord": {
        "value": "SYNTHETIC APPLICANT",
        "source": "SYNTHETIC-SOURCE",
        "asOf": "2026-10-15T09:29:58Z"
      },
      "holderType": {
        "value": "individual",
        "source": "SYNTHETIC-SOURCE",
        "asOf": "2026-10-15T09:29:58Z"
      }
    }
  },
  "assessment": {
    "outcome": "pass",
    "policyVersion": "SYNTHETIC-POLICY-1",
    "reasonCodes": [
      "PAN_ACTIVE"
    ]
  },
  "evidenceReferences": [
    {
      "kind": "source-receipt",
      "reference": "SYNTHETIC-EVIDENCE-0001"
    }
  ],
  "completedAt": "2026-10-15T09:30:00Z"
}

documentation

Documentation

Detailed documentation, including every schema and error code, is shared during onboarding. Book a demo and we'll walk your engineers through the contract.

Bring your engineers

We'll go through the contract with your team and map it to your flow.

Book a demo

Or write to sales@koshio.in