The AltScore API is a REST API served over HTTPS/TLS 1.3. All request and response bodies are JSON. All endpoints require authentication. No endpoint is publicly accessible without a valid credential.
API-ALTSCORE-001 · Base URL: https://api.altscore.in/v1Retrieve AltScore credit scores, risk bands, PD estimates, and SHAP reason codes for individual retailers.
Manage retailer consent lifecycle. Grant, revoke, check, and export consent records. Called internally by all services.
ERP connector SDK posts invoice and payment batches. Authenticated via mTLS + API key. HMAC-signed payloads.
File score grievances, check status, request explanation. Human review within 24h acknowledgement SLA.
Distributor onboarding, model promotion, compliance reports, RBAC management. FIDO2 authenticated.
| Header | Required | Description |
|---|---|---|
Authorization | required | Bearer <jwt_token> for external APIs. See Section 02. |
X-Client-ID | required | Lender or distributor identifier. Must match JWT subject claim. |
X-Request-ID | optional | Client-supplied idempotency key (UUID). Returned in response for tracing. |
Content-Type | required (POST/PUT) | Must be application/json. |
Accept-Language | optional | en or hi. Reason codes returned in specified language. Default: en. |
| Property | Value |
|---|---|
| Token type | JWT (JSON Web Token) |
| Signing algorithm | RS256 (RSA 2048-bit + SHA-256) |
| Token TTL | 1 hour. Refresh before expiry. |
| Required claims | sub (lender_id), iss (altscore.in), exp, iat, jti (unique per token) |
| Additional header | X-Client-ID: <lender_id> must match sub claim |
| Token endpoint | POST /v1/auth/token — body: {"client_id":"…","client_secret":"…"} |
| Key rotation | Signing keys rotated every 6 months. 2-week overlap period. JWKS endpoint: GET /.well-known/jwks.json |
ERP connectors use mTLS + API key. The client certificate (per distributor, 90-day rotation) handles transport-level identity. The X-API-Key header provides application-level identity. Payload HMAC-SHA256 signature must be included in X-Payload-Signature header.
Admin API requires FIDO2/WebAuthn hardware key + SAML 2.0 SSO token. No username/password authentication. Session tokens are short-lived (15 minutes) and non-renewable; re-authentication required per session.
All APIs enforce consent-scoped authorization on top of authentication. An authenticated NBFC partner may only retrieve scores for retailers who have explicitly named that lender in their active consent record. The 403 Forbidden response does not distinguish between "retailer not found" and "retailer exists but consent not granted" — both return 403 to prevent information leakage.
The Score API is the primary interface for NBFC lending partners. All endpoints require JWT RS256 authentication. Rate limit: 100 requests/minute per lender.
| Status | Error Code | Meaning |
|---|---|---|
| 400 | INVALID_REQUEST | Missing or invalid retailer_id / purpose field |
| 401 | TOKEN_EXPIRED / TOKEN_INVALID | JWT expired or signature invalid |
| 403 | CONSENT_NOT_GRANTED | Retailer has not consented to this lender (or retailer not found — intentionally ambiguous) |
| 404 | RETAILER_NOT_SCORED | Retailer exists and consented but no score computed yet (e.g., data too fresh) |
| 422 | DATA_INSUFFICIENT | Completeness <50% — scoring blocked |
| 429 | RATE_LIMIT_EXCEEDED | 100 req/min exceeded. Headers: Retry-After, X-RateLimit-Reset |
| 503 | SERVICE_UNAVAILABLE | Consent Service unreachable (fail-safe block) |
POST /v1/score.| Parameter | Type | Default | Description |
|---|---|---|---|
months | integer | 6 | Number of monthly snapshots to return (max 12) |
retailer_id required for POST /v1/score. GST is not stored post-lookup — only the UUID is returned.| Parameter | Required | Description |
|---|---|---|
gst | required | 15-character GSTIN of the retailer |
Internal-use API for consent lifecycle management. Called by other services (Scoring Engine, Score API) and by the WhatsApp Webhook Handler. NBFC partners do not call this API directly.
consent.granted Kafka event.consent.revoked event which stops scoring and invalidates Score API cache. Consent record is NOT deleted (7-year audit retention).| Parameter | Required |
|---|---|
retailer_id | required |
lender_id | required |
Used exclusively by the ERP Connector SDK deployed at distributor sites. Requires mTLS client certificate + API key + HMAC payload signature. Rate limit: 10 batches/hour per distributor.
| Header | Description |
|---|---|
X-API-Key | Distributor API key (32-byte hex, rotated annually) |
X-Payload-Signature | HMAC-SHA256 of request body using distributor's signing secret |
X-ERP-Type | tally_prime | sap_b1 | csv |
X-Batch-ID | Client-generated UUID for idempotency (same batch_id = no-op if already processed) |
grievance.filed event.Internal-only. Requires FIDO2 hardware key + SSO. All operations are audit-logged. Not accessible from outside the VPN.
| Method | Endpoint | Description |
|---|---|---|
| POST | /v1/admin/distributors | Onboard a new distributor; issues mTLS cert + API key |
| POST | /v1/admin/distributors/{id}/rotate-key | Rotate a distributor's API key and mTLS cert |
| POST | /v1/admin/models/promote | Promote a challenger model to champion (two-person sign-off enforced) |
| POST | /v1/admin/models/rollback | Rollback to previous champion model (<10 min) |
| GET | /v1/admin/grievances | List open grievances with SLA status |
| GET | /v1/admin/compliance/report | Generate DPDP/RBI compliance report for specified date range |
| GET | /v1/admin/audit/events | Query audit log (DPO/Legal access; read-only) |
| PUT | /v1/admin/retailers/{id}/erasure | Process Right-to-Erasure request (30-day SLA timer started) |
| GET | /v1/admin/retailers/{id}/export | Data portability export for retailer (15-day SLA, JSON) |
| HTTP Status | Error Code | Description | Action |
|---|---|---|---|
| 400 | INVALID_REQUEST | Malformed JSON or missing required field | Fix request body per schema |
| 400 | INVALID_RETAILER_ID | retailer_id format invalid (must be ret_ prefix + 16 hex chars) | Use /v1/retailers/lookup first |
| 401 | TOKEN_EXPIRED | JWT exp claim in the past | Refresh token via POST /v1/auth/token |
| 401 | TOKEN_INVALID | JWT signature verification failed | Re-authenticate; check signing key rotation |
| 401 | TOKEN_MISSING | Authorization header absent | Add Bearer token header |
| 403 | CONSENT_NOT_GRANTED | Retailer not consented to this lender or retailer unknown | Initiate consent flow via distributor dashboard |
| 403 | SCOPE_MISMATCH | Requested purpose not in consent scope | Verify purpose matches consent record |
| 404 | RETAILER_NOT_SCORED | No score available yet (consented but data too new) | Retry after next pipeline run (up to 24h) |
| 409 | BATCH_ALREADY_PROCESSED | X-Batch-ID already received and processed | Idempotent — original result stands |
| 422 | DATA_INSUFFICIENT | Completeness <50% — scoring blocked | Distributor must supply more ERP data |
| 429 | RATE_LIMIT_EXCEEDED | 100 req/min exceeded | Back off per Retry-After header |
| 500 | INTERNAL_ERROR | Unexpected server error | Retry with exponential backoff; contact support if persists |
| 503 | SERVICE_UNAVAILABLE | Consent Service or Scoring Engine temporarily unavailable | Retry after 30s; fail-safe block active |
| API Group | Limit | Window | Scope | Response on Breach |
|---|---|---|---|---|
| Score API | 100 requests | 1 minute | Per lender (JWT sub) | 429 + Retry-After + X-RateLimit-Reset |
| Score API | 5,000 requests | 24 hours | Per lender | 429 with daily quota context |
| Ingestion API | 10 batches | 1 hour | Per distributor | 429 |
| Ingestion API | 1,000 records/batch | Per request | Per batch payload | 400 BATCH_TOO_LARGE |
| Grievance API | 5 filings | 24 hours | Per retailer | 429 |
| Auth token endpoint | 10 requests | 1 minute | Per client_id | 429 (brute-force protection) |
APIs are versioned by URL path prefix (/v1/). A new major version is only created when a breaking change is unavoidable. Minor and patch changes are non-breaking and applied in-place.
| Version | Status | Support Until | Notes |
|---|---|---|---|
| v1 | CURRENT | Minimum 24 months from GA | This document |
| v2 | PLANNED | TBD | RBI Account Aggregator integration; breaking changes TBD |
NBFC partners receive 90 days advance notice before any breaking change deployment, via email + dashboard notification. Version sunset is announced at least 6 months before the old version is decommissioned.