> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finscreener.in/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete API documentation for Finscreener

## Base URL

All API requests should be made to:

```
https://api.finscreener.in
```

## Authentication

The Finscreener Developer API uses **API key authentication**. You must first generate an API key from your Finscreener dashboard.

### Login with API Key

```bash theme={null}
POST /api/auth/login
Content-Type: application/json

{
  "api_key": "fsk_your_api_key"
}
```

<Warning>
  Email/password login is **not supported** for the Developer API. You must use an API key (format: `fsk_xxx`).
</Warning>

**Response:**

```json theme={null}
{
  "token": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIs...",
    "token_type": "bearer"
  }
}
```

Use the `access_token` in subsequent requests:

```bash theme={null}
Authorization: Bearer <access_token>
```

## Token Refresh

Access tokens expire after a set period. Use the refresh token to get a new access token:

```bash theme={null}
POST /api/auth/refresh-token
Content-Type: application/json

{
  "refresh_token": "your_refresh_token"
}
```

## Response Format

All responses are JSON formatted:

### Success Response

```json theme={null}
{
  "data": { ... },
  "message": "Success"
}
```

### Error Response

```json theme={null}
{
  "detail": "Error message describing what went wrong"
}
```

## HTTP Status Codes

| Code | Description                             |
| ---- | --------------------------------------- |
| 200  | Success                                 |
| 201  | Created                                 |
| 400  | Bad Request - Invalid parameters        |
| 401  | Unauthorized - Invalid or expired token |
| 403  | Forbidden - Insufficient permissions    |
| 404  | Not Found - Resource doesn't exist      |
| 422  | Validation Error - Invalid input data   |
| 429  | Rate Limited - Too many requests        |
| 500  | Server Error                            |

## Rate Limits

API rate limits vary by endpoint and subscription tier:

| Endpoint Type | Free Tier | Premium   |
| ------------- | --------- | --------- |
| Search        | 100/day   | Unlimited |
| Details       | 100/day   | 1000/day  |
| Screener      | 10/day    | 100/day   |

### Rate Limit Headers

Detail endpoint responses include rate limit headers:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 2026-03-25T23:59:59Z
```

| Header                  | Description                          |
| ----------------------- | ------------------------------------ |
| `X-RateLimit-Limit`     | Maximum requests allowed per day     |
| `X-RateLimit-Remaining` | Requests remaining in current window |
| `X-RateLimit-Reset`     | When the rate limit resets (UTC)     |

### Security Headers

All API responses include `Strict-Transport-Security` and `X-Content-Type-Options: nosniff`. Responses also include `Cache-Control: no-store, private` to prevent sensitive data from being cached by proxies.

<Note>
  For detailed security information, see our [Security & Data Protection](/security) page.
</Note>

## API Sections

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/auth/login">
    Login, token refresh, and validation
  </Card>

  <Card title="User" icon="user" href="/api-reference/user/profile">
    User profile and subscription information
  </Card>

  <Card title="Screener" icon="filter" href="/api-reference/screener/search">
    Execute and manage FQL queries
  </Card>

  <Card title="Filters" icon="list" href="/api-reference/filters/companies">
    Filter companies, directors, and GST records
  </Card>

  <Card title="Details" icon="file" href="/api-reference/details/company">
    Get detailed company, director, and GST information
  </Card>

  <Card title="Watchlist" icon="bookmark" href="/api-reference/watchlist/list">
    Create and manage watchlists
  </Card>

  <Card title="Orders" icon="cart-shopping" href="/api-reference/orders/list">
    Create and manage data orders
  </Card>

  <Card title="Recently Registered" icon="clock" href="/api-reference/recently-registered/gst">
    Access newly registered GST registrations
  </Card>

  <Card title="Reference" icon="book" href="/api-reference/reference/nic-codes">
    NIC, HSN, and SAC code lookups
  </Card>

  <Card title="CRM" icon="users" href="/api-reference/crm/orders">
    CRM integration endpoints for Zoho
  </Card>
</CardGroup>

## SDKs and Tools

### Python

```python theme={null}
import requests

class FinscreenerClient:
    def __init__(self, api_key):
        self.base_url = "https://api.finscreener.in"
        self.api_key = api_key
        self.token = None

    def login(self):
        response = requests.post(
            f"{self.base_url}/api/auth/login",
            json={"api_key": self.api_key}
        )
        self.token = response.json()["token"]["access_token"]
        return self.token

    def _headers(self):
        return {"Authorization": f"Bearer {self.token}"}

    def search(self, query, entity_type="company", page=1, limit=10):
        return requests.post(
            f"{self.base_url}/api/screener/search",
            json={"query": query, "type": entity_type, "page": page, "limit": limit},
            headers=self._headers()
        ).json()

    def filter_companies(self, **filters):
        return requests.get(
            f"{self.base_url}/api/company/company-filter",
            params=filters,
            headers=self._headers()
        ).json()

    def get_company_details(self, cin):
        return requests.get(
            f"{self.base_url}/api/company/details",
            params={"cin": cin},
            headers=self._headers()
        ).json()

# Usage
client = FinscreenerClient("fsk_your_api_key")
client.login()
results = client.filter_companies(company="Reliance", state="Maharashtra")
```

### JavaScript

```javascript theme={null}
const axios = require('axios');

class FinscreenerClient {
  constructor(apiKey) {
    this.baseUrl = 'https://api.finscreener.in';
    this.apiKey = apiKey;
    this.token = null;
  }

  async login() {
    const response = await axios.post(`${this.baseUrl}/api/auth/login`, {
      api_key: this.apiKey
    });
    this.token = response.data.token.access_token;
    return this.token;
  }

  get headers() {
    return { Authorization: `Bearer ${this.token}` };
  }

  async search(query, type = 'company', page = 1, limit = 10) {
    const response = await axios.post(
      `${this.baseUrl}/api/screener/search`,
      { query, type, page, limit },
      { headers: this.headers }
    );
    return response.data;
  }

  async filterCompanies(filters) {
    const response = await axios.get(
      `${this.baseUrl}/api/company/company-filter`,
      { params: filters, headers: this.headers }
    );
    return response.data;
  }

  async getCompanyDetails(cin) {
    const response = await axios.get(
      `${this.baseUrl}/api/company/details`,
      { params: { cin }, headers: this.headers }
    );
    return response.data;
  }
}

// Usage
const client = new FinscreenerClient('fsk_your_api_key');
await client.login();
const results = await client.filterCompanies({ company: 'Reliance', state: 'Maharashtra' });
```

### cURL

```bash theme={null}
# Login with API key
TOKEN=$(curl -s -X POST https://api.finscreener.in/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"api_key": "fsk_your_api_key"}' | jq -r '.token.access_token')

# Filter companies
curl -X GET "https://api.finscreener.in/api/company/company-filter?company=Reliance&state=Maharashtra" \
  -H "Authorization: Bearer $TOKEN"

# Get company details
curl -X GET "https://api.finscreener.in/api/company/details?cin=L17110MH1973PLC019786" \
  -H "Authorization: Bearer $TOKEN"
```