# Vismrit Public API Documentation

Base URL: `https://api.sinhcoms.com`

> This document is generated from the public website API catalogue. Internal-only APIs are excluded.

## Authentication

Every public API request is authenticated by the shared Vismrit API layer. Supply the key using one of:

- `Authorization: Bearer YOUR_API_KEY`
- `X-API-Key: YOUR_API_KEY`
- `api_key=YOUR_API_KEY` as a query or form parameter

The API key must be active, authorized for the requested API product, attached to an active subscription, not expired, and allowed by the configured IP/domain whitelist. Rate limits are enforced per subscription.

## Common HTTP responses

| Status | Meaning |
|---:|---|
| `200` | Request completed successfully |
| `400` | Invalid or missing request data |
| `401` | Missing, invalid, inactive, expired or unauthorized API key |
| `422` | Validation error on supported endpoints |
| `429` | Daily request limit exceeded |
| `500` | Server-side processing error |
| `502` / `504` | Upstream/WebSocket processing failure or timeout |

---

## Aadhaar API

**Product ID:** `api-aadhaar`

The Aadhaar API exposes the multi-step flow already represented by the active API controller catalogue: start a workflow, work through captcha handling and continue to the OTP stage. It is intended as a developer integration building block inside an authorised application workflow rather than a standalone customer interface.

### Endpoints

| Method | Route | Purpose |
|---|---|---|
| `ANY` | `https://api.sinhcoms.com/aadhaar` | Index |
| `ANY` | `https://api.sinhcoms.com/aadhaar/captcha` | Captcha |
| `ANY` | `https://api.sinhcoms.com/aadhaar/otp` | Otp |
| `ANY` | `https://api.sinhcoms.com/aadhaar/start` | Start |

### Capabilities

- Start an Aadhaar-related workflow session
- Handle captcha stages exposed by the API
- Continue the session into OTP processing
- Use Vismrit API keys and account-level access controls around requests

### Typical use cases

- Authorised identity-related onboarding flows
- Internal workflow automation where Aadhaar interaction is legally and contractually permitted
- Applications that need to orchestrate the existing multi-step Aadhaar controller flow

### Integration flow

1. Choose an active subscription tier
2. Generate or assign an API key from API Access
3. Configure whitelist restrictions where required
4. Integrate the published /aadhaar routes in sequence
5. Track request usage and errors from the API dashboard

### Authentication & access notes

Send the API key as Authorization: Bearer YOUR_API_KEY or X-API-Key: YOUR_API_KEY. The key must be active, assigned to the Aadhaar API product, backed by an active subscription and allowed by your whitelist settings.

### Example request

```text
curl -X POST "https://api.sinhcoms.com/aadhaar/start" 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/x-www-form-urlencoded" 
  --data-urlencode "aadhaar=YOUR_AADHAAR_VALUE"

# Continue the same session
curl -X POST "https://api.sinhcoms.com/aadhaar/captcha" 
  -H "Authorization: Bearer YOUR_API_KEY" 
  --data-urlencode "sessionId=SESSION_ID" 
  --data-urlencode "captcha=CAPTCHA_CODE"

curl -X POST "https://api.sinhcoms.com/aadhaar/otp" 
  -H "Authorization: Bearer YOUR_API_KEY" 
  --data-urlencode "sessionId=SESSION_ID" 
  --data-urlencode "otp=OTP_VALUE"
```

### Example response

```json
{
  "status": "captcha",
  "message": "Enter captcha code",
  "sessionId": "SESSION_ID",
  "captcha_base64": "..."
}

# After captcha
{
  "status": "otp",
  "message": "Captcha accepted. Submit OTP.",
  "sessionId": "SESSION_ID"
}
```

### Documented errors

- 400 \| Aadhaar, sessionId, captcha or OTP input is missing
- 401 \| API key authentication or product authorization failed
- 429 \| Daily request limit exceeded
- 504 \| Upstream WebSocket timed out

### Notes

Aadhaar and identity data can be sensitive and regulated. Use this API only for lawful, authorised purposes and apply appropriate consent, data-minimisation, security and retention controls.

Public detail page: https://www.sinhcoms.com/products/apis/aadhaar

---

## Background Remover API

**Product ID:** `api-background-remover`

The Background Remover product represents image background-removal capability in the Vismrit API catalogue. The current controller catalogue may show this legacy product separately from the active Image controller, so the public page clearly distinguishes product availability from currently published endpoints.

### Endpoints

_No active public endpoint catalogue is currently published for this product._

### Capabilities

- Remove image backgrounds programmatically
- Use image processing inside upload or content workflows
- Manage subscription limits and API-key access from the dashboard

### Typical use cases

- Product-photo processing
- Profile or ID image preparation
- Creative tools that need transparent or isolated subjects
- Batch image-cleanup workflows

### Integration flow

1. Choose an available plan
2. Create or assign an API key
3. Review the published endpoint catalogue
4. Send supported image input to the active image endpoint
5. Handle the returned processed image in your application

### Authentication & access notes

Use an API key assigned to the Background Remover subscription. The public route is currently served by the Image controller at /image/background_remover; the website documentation bridges the legacy product ID to that active route.

### Example request

```text
curl -X POST "https://api.sinhcoms.com/image/background_remover" 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "image_base64": "data:image/png;base64,..."
  }'
```

### Example response

```json
{
  "status": "success",
  "data": {
    "message": "Background removed successfully",
    "image_base64": "..."
  },
  "timestamp": "YYYY-MM-DD HH:MM:SS"
}
```

### Documented errors

- 400 \| Image input is missing or invalid
- 401 \| API key authentication or product authorization failed
- 429 \| Daily request limit exceeded
- 502 \| Background-removal upstream returned an invalid or failed response
- 504 \| Background-removal WebSocket timed out

### Notes

Endpoint availability is displayed live from the API controller catalogue. If no active endpoint is published for this legacy product ID, use the currently published Image API details before integrating.

### Active plans

| Plan | Daily limit | Monthly limit | Price / month |
|---|---:|---:|---:|
| Star | 100,000 | 3,000,000 | INR 499.00 |

Public detail page: https://www.sinhcoms.com/products/apis/background-remover

---

## Grank API

**Product ID:** `api-grank`

The GRank API exposes the ranking utility through an active controller catalogue containing health, search and position routes. It is intended for applications that need to query the ranking workflow programmatically and manage usage through the normal Vismrit API subscription controls.

### Endpoints

| Method | Route | Purpose |
|---|---|---|
| `ANY` | `https://api.sinhcoms.com/grank` | Index |
| `ANY` | `https://api.sinhcoms.com/grank/health` | Health |
| `ANY` | `https://api.sinhcoms.com/grank/position` | Position |
| `ANY` | `https://api.sinhcoms.com/grank/search` | Search |

### Capabilities

- Check API health before workflow execution
- Run the published search operation
- Query the published position operation
- Manage keys, quotas and whitelist restrictions centrally

### Typical use cases

- SEO monitoring dashboards
- Keyword or result-position workflows
- Scheduled ranking checks
- Internal reporting and search-visibility tools

### Integration flow

1. Select a GRank subscription tier
2. Create or assign an API key
3. Use the health route for readiness checks
4. Integrate search and position routes according to the expected parameters
5. Store only the result data your application actually needs and monitor usage

### Authentication & access notes

Use Authorization: Bearer YOUR_API_KEY or X-API-Key. Search and position requests accept JSON, form-data or x-www-form-urlencoded input.

### Example request

```text
curl -X POST "https://api.sinhcoms.com/grank/search" 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "keyword": "dentist",
    "latitude": 28.4595,
    "longitude": 77.0266,
    "radius_km": 5,
    "business_name": "32 Dental House",
    "place_id": "",
    "country_code": "IN",
    "language_code": "en",
    "max_results": 20
  }'

# Position requires keyword, latitude, longitude and business_name
curl -X POST "https://api.sinhcoms.com/grank/position" 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "keyword": "dentist",
    "latitude": 28.4595,
    "longitude": 77.0266,
    "business_name": "32 Dental House",
    "radius_km": 5,
    "country_code": "IN",
    "language_code": "en",
    "max_results": 20
  }'
```

### Example response

```json
The GRank controller returns the ranking-service JSON received from its upstream WebSocket workflow. Check the ok flag and handle non-2xx status values returned by the service.
```

### Documented errors

- 422 \| Required search or position parameter is missing/invalid
- 401 \| API key authentication or product authorization failed
- 429 \| Daily request limit exceeded
- 502 \| Ranking WebSocket/upstream service error

### Notes

Search-engine behaviour and third-party result formats can change. Build calling applications to tolerate transient errors and changing result availability.

### Active plans

| Plan | Daily limit | Monthly limit | Price / month |
|---|---:|---:|---:|
| Star | 1,000,000 | 10,000,000 | INR 499.00 |

Public detail page: https://www.sinhcoms.com/products/apis/grank

---

## Gst API

**Product ID:** `api-gst`

The GST API exposes a session-based workflow through the active controller catalogue. Published routes include starting the flow, submitting GSTIN plus captcha data and refreshing captcha state when needed. This lets an application orchestrate the existing GST workflow through a controlled API subscription.

### Endpoints

| Method | Route | Purpose |
|---|---|---|
| `ANY` | `https://api.sinhcoms.com/gst` | Index |
| `POST` | `https://api.sinhcoms.com/gst/data` | Body JSON: { sessionId, GSTIN, captcha } |
| `GET` | `https://api.sinhcoms.com/gst/refresh_captcha` | (Optional) GET /api/v1/gst/refresh-captcha?sessionId=... |
| `GET` | `https://api.sinhcoms.com/gst/start` | WS: send {type:"start"} -> receive {type:"captcha", sessionId, captcha(base64)} |

### Capabilities

- Start a GST workflow session
- Receive or refresh captcha state
- Submit GSTIN and captcha data through the published POST route
- Apply API-key, quota and whitelist controls around requests

### Typical use cases

- Business onboarding workflows that need GST-related data
- Internal vendor or customer verification processes
- Applications that need to orchestrate the existing GST session and captcha flow

### Integration flow

1. Choose a GST API tier
2. Generate or assign an API key
3. Call the start route and retain the returned session context
4. Submit GSTIN and captcha data to the published data route
5. Refresh captcha when required and handle errors explicitly

### Authentication & access notes

Use Authorization: Bearer YOUR_API_KEY or X-API-Key. Keep the returned sessionId between GST start, data submission and captcha-refresh requests.

### Example request

```text
curl -X GET "https://api.sinhcoms.com/gst/start" 
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X POST "https://api.sinhcoms.com/gst/data" 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/x-www-form-urlencoded" 
  --data-urlencode "sessionId=SESSION_ID" 
  --data-urlencode "gst=GSTIN_VALUE" 
  --data-urlencode "captcha=CAPTCHA_CODE"

curl -X GET "https://api.sinhcoms.com/gst/refresh_captcha?sessionId=SESSION_ID" 
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example response

```json
{
  "sessionId": "SESSION_ID",
  "image": "data:image/png;base64,..."
}

# /gst/data returns the GST workflow data payload when the upstream service succeeds.
```

### Documented errors

- 400 \| sessionId, GSTIN/gst or captcha is missing
- 401 \| API key authentication or product authorization failed
- 429 \| Daily request limit exceeded
- 500 \| GST processing failed
- 502 \| Unexpected upstream response

### Notes

GST data can be business-sensitive. Validate your lawful basis and downstream use, and do not log sensitive payloads unnecessarily.

### Active plans

| Plan | Daily limit | Monthly limit | Price / month |
|---|---:|---:|---:|
| Star | 100,000 | 3,000,000 | INR 499.00 |

Public detail page: https://www.sinhcoms.com/products/apis/gst

---

## Image API

**Product ID:** `api-image`

The Image API is the active image-processing controller in the current catalogue. Its published background-removal route can be integrated into server-side or application workflows while subscription, API-key and request-limit controls remain managed by the Vismrit API platform.

### Endpoints

| Method | Route | Purpose |
|---|---|---|
| `ANY` | `https://api.sinhcoms.com/image/background_remover` | Background Remover |

### Capabilities

- Call the active /image/background_remover route
- Process image input through a managed API subscription
- Control access with API keys and whitelist rules
- Track request volume and errors

### Typical use cases

- Product-photo cleanup
- Profile-image preparation
- Design and content tooling
- Automated image-processing pipelines

### Integration flow

1. Choose an Image API plan
2. Generate or assign an API key
3. Prepare the supported image input format
4. Call the published background-removal endpoint
5. Store or return the processed image according to your application workflow

### Authentication & access notes

Use Authorization: Bearer YOUR_API_KEY or X-API-Key. The image endpoint accepts image or image_base64 from form/query input, or JSON containing either field.

### Example request

```text
curl -X POST "https://api.sinhcoms.com/image/background_remover" 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "image_base64": "data:image/png;base64,..."
  }'
```

### Example response

```json
{
  "status": "success",
  "data": {
    "message": "Background removed successfully",
    "image_base64": "..."
  },
  "timestamp": "YYYY-MM-DD HH:MM:SS"
}
```

### Documented errors

- 400 \| Image is required or request image data cannot be encoded
- 401 \| API key authentication or product authorization failed
- 429 \| Daily request limit exceeded
- 502 \| Invalid/failed background-removal upstream response
- 504 \| Background-removal WebSocket timeout

### Notes

Large image payloads can affect response time and bandwidth. Validate file size and type before sending requests and use server-side integration for sensitive uploads.

Public detail page: https://www.sinhcoms.com/products/apis/image

---

## Ip API

**Product ID:** `api-ip`

The IP API provides a lightweight HTTP endpoint for applications that need IP-related lookup data through the Vismrit API platform. The active catalogue currently publishes a GET /ip route, while subscription and usage controls are handled by the standard API-key system.

### Endpoints

| Method | Route | Purpose |
|---|---|---|
| `GET` | `https://api.sinhcoms.com/ip` | Index |

### Capabilities

- Call the published GET /ip endpoint
- Pass the IP-related input expected by the controller
- Apply API-key and whitelist restrictions
- Track daily and monthly request usage

### Typical use cases

- Server-side IP lookup inside security or analytics workflows
- Operational enrichment of request data
- Developer utilities that need a simple IP API endpoint

### Integration flow

1. Subscribe to an IP API tier
2. Generate or reuse the appropriate API key
3. Whitelist the calling environment if required
4. Call GET /ip with the expected parameters
5. Handle response and rate-limit states in your application

### Authentication & access notes

Use Authorization: Bearer YOUR_API_KEY or X-API-Key. If the ip query parameter is omitted, the endpoint analyses the caller IP seen by the API service.

### Example request

```text
curl -X GET "https://api.sinhcoms.com/ip?ip=8.8.8.8" 
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example response

```json
{
  "ip": "8.8.8.8",
  "is_valid": true,
  "version": 4,
  "is_private": false,
  "is_reserved": false,
  "is_loopback": false,
  "hostname": null,
  "country": "...",
  "location": {},
  "city": "...",
  "asn": "...",
  "ip_risk": 0,
  "static_ip_score": 0
}
```

### Documented errors

- 400 \| Invalid IP format
- 401 \| API key authentication or product authorization failed
- 429 \| Daily request limit exceeded

### Notes

Do not use IP-derived data as the sole basis for high-impact identity or access decisions. Treat it as contextual network information.

### Active plans

| Plan | Daily limit | Monthly limit | Price / month |
|---|---:|---:|---:|
| Star | 100,000 | 3,000,000 | INR 499.00 |

Public detail page: https://www.sinhcoms.com/products/apis/ip

---

## Pincode API

**Product ID:** `api-pincode`

The Pincode API controller catalogue describes the main endpoint as fetching Post Office details based on Country and Pin Code. It can be used to enrich address forms, validate postal context or look up service-area information from another application.

### Endpoints

| Method | Route | Purpose |
|---|---|---|
| `ANY` | `https://api.sinhcoms.com/pincode` | Main API to fetch Post Office details based on Country and Pin Code |

### Capabilities

- Look up post-office details by country and pincode
- Use a single API-key-controlled endpoint
- Apply subscription quotas and whitelist restrictions
- Integrate lookup results into forms or address workflows

### Typical use cases

- Address-entry assistance
- Postal and service-area validation
- CRM or order workflows that need post-office context
- Location-data enrichment during onboarding

### Integration flow

1. Choose a Pincode API plan
2. Create or assign an API key
3. Call the published /pincode endpoint with the expected country and pin-code values
4. Validate response data before applying it to business logic
5. Monitor usage from the API dashboard

### Authentication & access notes

Use Authorization: Bearer YOUR_API_KEY or X-API-Key. country uses a supported two-letter country code; pin is the postal code or, for India, can also be a post-office search value.

### Example request

```text
curl -X GET "https://api.sinhcoms.com/pincode?country=IN&pin=110001" 
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example response

```json
The endpoint returns the postal-provider JSON response. For India it uses the configured India postal lookup; supported non-IN countries use the configured Zippopotam lookup.
```

### Documented errors

- 400 \| pin is missing
- 401 \| API key authentication or product authorization failed
- 429 \| Daily request limit exceeded
- Provider error \| Postal provider did not return a usable result

### Notes

Postal data can change. Applications should handle missing or multiple records gracefully instead of assuming a single permanent result.

### Active plans

| Plan | Daily limit | Monthly limit | Price / month |
|---|---:|---:|---:|
| Star | 100,000 | 3,000,000 | INR 499.00 |

Public detail page: https://www.sinhcoms.com/products/apis/pincode

---