Developers

Build on the claims infrastructure layer.

A clean REST API, signed webhooks and typed SDKs to embed eligibility, claims and settlements into your own products. Secured by scoped keys + RBAC, mapped to the Nigerian Member ID schema.

Quickstart

Pick your language. Ship in an afternoon.

Every code path below is idempotent, cursor-paginated and safe to retry. Amounts are always minor units (kobo) - no float rounding surprises at settlement time.

quickstart.shcurl
# List recent claims (bearer + tenant header required)
curl https://api.vetrainsure.com/v1/claims \
  -H "Authorization: Bearer $VETRA_API_KEY" \
  -H "x-tenant-id: tnt_hygeia"

# → 200 OK
# {
#   "data": [
#     {
#       "reference": "CLM-24817",
#       "providerName": "St. Nicholas Hospital",
#       "memberId": "HYG-DNG-00234-PR",
#       "amount": 48500000,
#       "status": "IN_REVIEW",
#       "risk": "MEDIUM"
#     }
#   ],
#   "page": { "next": "clm_24816" }
# }
quickstart.tsTypeScript
// npm i @vetra/sdk-node
import { Vetra } from '@vetra/sdk-node';

const vetra = new Vetra({
  apiKey: process.env.VETRA_API_KEY!,
  tenantId: process.env.VETRA_TENANT_ID!,
});

// List claims (cursor-paginated)
const { data, page } = await vetra.claims.list({
  status: 'IN_REVIEW',
  limit: 25,
});

// Amounts are minor units (kobo) — always
for (const c of data) {
  const naira = (c.amount / 100).toLocaleString('en-NG', {
    style: 'currency',
    currency: 'NGN',
  });
  console.log(`${c.reference} · ${naira} · ${c.status}`);
}
quickstart.pyPython
# pip install vetra
from vetra import Vetra

client = Vetra(
    api_key=os.environ["VETRA_API_KEY"],
    tenant_id=os.environ["VETRA_TENANT_ID"],
)

# Verify eligibility for a Vetra Member ID
eligibility = client.eligibility.check("HYG-DNG-00234-PR")

if eligibility.covered:
    print(f"Covered on plan: {eligibility.plan}")
    print(f"Sessions left  : {eligibility.sessions_remaining}")
else:
    print(f"Not covered: {eligibility.reason}")

Scoped API keys are per-environment. Use a sandbox key for the quickstart; switch to a production key once your tenant is live. Rotate on staff offboarding.

Core endpoints

Resource-oriented, predictable, boring in the best way.

Seven endpoints do 90% of what most integrations need. The full reference lives in /documentation/api-reference.

MethodPathPurpose
POST/v1/claimsSubmit a claim. Returns the assigned reference + adjudication state.
GET/v1/claimsList claims with filters (status, dates, provider, member).
GET/v1/claims/:idFetch a single claim with line items, queries, attachments and the risk trail.
POST/v1/authorizationsFile a pre-authorisation request. Urgency tier + auto-approval rules applied server-side.
GET/v1/eligibility/:memberIdEligibility verdict for a Vetra Member ID - millisecond lookup, no polling.
GET/v1/settlementsList settlement runs, filter by provider or billing month, drill through to remittances.
POST/v1/providers/linkSend a network link request to a cross-tenant ProviderOrg from the directory.
Full API reference OpenAPI 3.1 spec on request - generate clients in your language of choice.
Signed webhooks

Real-time events for every state change.

Vetra emits a signed webhook every time a claim, PA, settlement or risk event transitions. Verify the X-Vetra-Signature HMAC against the raw body using your webhook secret - the sample on the right is the exact recipe.

  • claim.receivedClaim entered adjudication. Per-claim billing trigger to Vetra.
  • claim.queriedAdjudicator posted a query. Provider needs to respond.
  • claim.approvedApproved in full or part. Eligible for the next settlement run.
  • claim.rejectedDeclined with a coded reason. Provider may appeal where allowed.
  • claim.settledIncluded in a settlement run. Payment proof follows once uploaded.
  • pa.approvedPre-authorisation approved. Auth code included in payload.
  • pa.rejectedPre-authorisation rejected. Reason + appeal window included.
  • settlement.run.createdA new settlement run is ready for finance sign-off.
  • settlement.proof.uploadedBank proof of payment attached to a remittance.
  • ai.risk_event.recordedA structured fraud/risk flag was written to the audit trail.
verify-webhook.tsTypeScript
// Verify the signed webhook before trusting the payload
import crypto from 'node:crypto';

export function verify(rawBody: string, signatureHeader: string) {
  const expected = crypto
    .createHmac('sha256', process.env.VETRA_WEBHOOK_SECRET!)
    .update(rawBody)
    .digest('hex');

  const provided = signatureHeader.split(',')
    .find((p) => p.startsWith('v1='))?.slice(3);

  if (!provided) return false;
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(provided, 'hex'),
  );
}

Vetra retries with exponential backoff for up to 24 hours on non-2xx responses. Set your endpoint to be idempotent - reprocess the same event ID safely.

Public marketplace API

A JSON directory of NHIA-accredited HMOs. No auth. AI-crawler friendly.

Vetra's marketplace directory is exposed as a public JSON endpoint so search engines, AI answer engines and third-party comparison tools can consume the live roster without scraping HTML. No API key. Cacheable. Rate-limited but generous.

  • Verified against the public NHIA registry at nhia.gov.ng.
  • Includes accreditation status, provider network size, plan count and Verified Score.
  • Updated daily from operational rows on Vetra tenants.
public-directory.shcurl
# The marketplace directory is public + JSON-first + AI-crawler friendly
curl https://www.vetrainsure.com/api/marketplace/hmos

# → 200 OK — a compact directory of NHIA-accredited HMOs on Vetra
# Filter by slug list (comma-separated)
curl "https://www.vetrainsure.com/api/marketplace/hmos?slugs=hygeia-hmo,avon-hmo"
What you get

Everything you need to integrate.

REST API

Resource-oriented endpoints for claims, eligibility, authorizations and settlements.

Signed webhooks

Real-time events for claim status, PA decisions, settlements and fraud flags.

Scoped API keys

Per-environment keys with RBAC + tenant scoping enforced server-side.

Typed SDKs

Node/TypeScript + Python SDKs. OpenAPI 3.1 for anything else you need.

Sandbox tenants

A pre-seeded sandbox tenant with realistic Nigerian HMO data - built for demos.

Idempotency + retries

Every write accepts an idempotency key. Retry aggressively - we will dedupe.

AI-crawler friendly

Marketplace JSON endpoint served without auth for LLM + SEO discovery.

Auditable by design

Every write returns the actor, timestamp and audit ID for downstream compliance.

Start building on Vetra.

Request API access and we will get your team a sandbox key, the OpenAPI spec, and a Slack channel with the platform engineers who wrote it.