# FileSure API

> REST access to the Ministry of Corporate Affairs register: every company, LLP and director in India, the documents they have filed, and structured data extracted from those documents. Prepaid wallet in rupees, per-endpoint pricing, one-time company unlocks for documents and financials.

Base URL `https://api.filesure.in`. Every request carries the key in the `x-api-key` header. Test keys (`fsk_test_`) work on the sandbox companies with nothing charged.

OpenAPI document: https://api.filesure.in/portal/openapi-public.yaml (also https://api.filesure.in/portal/openapi-public.json). Everything in one file: https://api.filesure.in/llms-full.txt. Rendered reference: https://api.filesure.in/portal/docs. Rate card: https://api.filesure.in/pricing.html. Changelog: https://api.filesure.in/changelog.html.

---

## Use with your AI tool

Most integrations now start in an AI tool, so start there. Create a test key in the [Developer Portal](https://api.filesure.in/portal/dashboard/keys) and put it in an environment variable named `FILESURE_API_KEY` on your machine. Then paste this into Claude, Cursor, Codex or ChatGPT. The prompt tells the tool where the key is, so the key itself never goes into the chat:

```text
Read https://api.filesure.in/llms-full.txt in full before writing any code. It is the complete reference for the FileSure API, which gives programmatic access to the Indian MCA register: companies, LLPs and directors, the documents they have filed, and the financial data extracted from those documents.

My API key is in the environment variable FILESURE_API_KEY. Read it from there; never print it, never paste it into a file, never ask me to type it. It is a test key: it works on the sandbox companies listed in the reference and nothing is charged.

Then write a script that takes a company name, resolves it to a CIN, fetches the company's master data, and lists its most recent filings. Follow the reference for the base URL, the header that carries the key, the sandbox identifiers and the response envelope. Do not invent endpoints or fields that are not in the reference.
```

Change the last paragraph to whatever you are building. The reference explains what each call costs and when an unlock is needed, so the tool can tell you before it spends anything. When you are ready for real calls, put a live key in the same variable; those bill your wallet like any other request.

The same reference is available in four shapes, all generated from the source of this page, so none is ever behind it:

| What | Where | Use it for |
|---|---|---|
| Everything in one file | [`/llms-full.txt`](https://api.filesure.in/llms-full.txt) | Paste or attach the whole reference into one conversation, as above |
| Index | [`/llms.txt`](https://api.filesure.in/llms.txt) | Hand a tool the map of this reference; it follows the links it needs |
| One page per endpoint | `/reference/<endpoint>.md`, listed in the index | Tools that index documentation page by page |
| OpenAPI document | [`/portal/openapi-public.yaml`](https://api.filesure.in/portal/openapi-public.yaml) or [`/portal/openapi-public.json`](https://api.filesure.in/portal/openapi-public.json) | Any tool with an OpenAPI or custom-connector import |

**Claude.** Paste the prompt, or attach `llms-full.txt` to a Project so every conversation starts with it. A custom connector can import the OpenAPI document.

**Cursor.** Add `https://api.filesure.in/llms.txt` as a documentation source in Cursor's settings and reference it from chat with `@Docs`, or paste the prompt into a chat.

**Codex.** Put the prompt in the task, or name `https://api.filesure.in/llms-full.txt` in your project instructions.

**ChatGPT.** Paste the prompt, give a project `llms-full.txt` as a knowledge file, or import the OpenAPI document as an action.

All of the above has the tool write code against the API. To let the assistant call FileSure itself, connect it instead: [Connect your AI tool](https://api.filesure.in/reference/start-here/connect-your-ai-tool.md).

---

## Connect your AI tool

For an assistant that should call FileSure itself rather than write code against it, connect it to the FileSure MCP server. Every action in this reference becomes a tool the assistant can use: find a company, read its record, list its filings, read an extraction, check freshness, and so on. You ask in plain words; the assistant picks the call, makes it with your key, and reads the answer.

Address: `https://api.filesure.in/mcp`. Tools that can set a header send your key in `Authorization: Bearer` or `x-api-key`; tools that cannot sign in with your FileSure account instead. The setup for each tool is below. The [Developer Portal](https://api.filesure.in/portal/dashboard/keys) shows the same blocks with your key already filled in whenever you create one.

### Claude Code

```bash
claude mcp add --transport http filesure https://api.filesure.in/mcp --header "x-api-key: $FILESURE_API_KEY"
```

### Cursor

Add to `.cursor/mcp.json` (or the global one in your home folder):

```json
{ "mcpServers": { "filesure": { "url": "https://api.filesure.in/mcp", "headers": { "x-api-key": "fsk_test_YOUR_KEY" } } } }
```

### Codex

In `~/.codex/config.toml`:

```text
[mcp_servers.filesure]
url = "https://api.filesure.in/mcp"
http_headers = { "x-api-key" = "fsk_test_YOUR_KEY" }
```

### Claude.ai and Claude Desktop

Add a custom connector with the address `https://api.filesure.in/mcp` and nothing else. The tool sends you to the FileSure portal to sign in with your account; you pick which of your keys it should use and approve, and it is connected. The key itself never leaves FileSure: the tool holds a token bound to that key, and you can disconnect it any time from the API keys page, where connected tools are listed. Revoking the key disconnects it too.

If a tool cannot sign in, the keyed address is the fallback: `https://api.filesure.in/mcp/k/fsk_test_YOUR_KEY`. A key in a URL can end up in logs and history, so use a test key there, and revoke it from the portal when you are done.

### Paid actions ask first

Unlock, refresh and document fetch cost money. When the assistant reaches for one of them, the connector returns the price at your rate and what it buys instead of running it; the action runs only when the assistant calls again with your confirmation. Nothing is spent without a decision.

### Every call is an ordinary API call

Each tool call goes through the API with your key: it is billed at your rates, shows in your usage, and obeys the sandbox and your rate limit. Start with a test key; the assistant then has every tool on the sandbox companies and nothing is charged.

What each tool does, what it takes, what it returns and what it costs: [Tools of the connector](https://api.filesure.in/reference/start-here/tools-of-the-connector.md) for the rules they share, and the [Tool reference](https://api.filesure.in/reference/start-here/tool-reference.md) for each one.

---

## Tools of the connector

The FileSure connector gives an AI tool sixteen tools. Each one is an ordinary call to this API with your key: it is billed at your rates, shows in your usage, obeys your rate limit, and on a test key works on the sandbox and costs nothing. This page is the rules every tool follows; the [Tool reference](https://api.filesure.in/reference/start-here/tool-reference.md) describes each tool. How to connect a tool is on [Connect your AI tool](https://api.filesure.in/reference/start-here/connect-your-ai-tool.md).

### The tools

- **Sandbox identifiers**: `list_sandbox_entities`
- **Look up the register**: `find_company`, `get_company`, `list_filings`, `find_director`, `get_director`
- **Documents and financials**: `unlock_company`, `get_unlock_status`, `get_filing_document`, `list_extraction_forms`, `list_extraction_years`, `get_extraction`
- **Keep a company current**: `check_freshness`, `refresh_company`, `fetch_documents`
- **Your account**: `get_account`

Tools that read the register are billed per call at your rate for the endpoint behind them; the free ones (`list_sandbox_entities`, `get_unlock_status`, `check_freshness`, `get_account`) cost nothing on either key. Prices in the reference are the default rate card; if your account has negotiated rates, those apply.

### Paid actions ask first

`unlock_company`, `refresh_company`, `fetch_documents` spend money. Each takes a `confirm` flag. Called without it, the tool runs nothing: it looks up your rate for the action and returns a `quote` with the price, what it buys and how to proceed, and nothing is charged. The assistant is told to ask you before calling again with `confirm: true`, which runs the action and charges it. An action that is refused or fails is never charged, whatever the reason.

### What a result looks like

Every tool returns exactly one of four results:

| Result | When | What it carries |
|---|---|---|
| `success` | the API answered with JSON | the endpoint's `data` object unchanged, a one-line summary, and what the call cost and left in the wallet |
| `file` | a filing PDF | the PDF as a resource, up to 10 MB, with its name, type and size, and a summary |
| `quote` | a paid action called without `confirm: true` | your price for the action, what it buys, how to proceed; nothing ran |
| `error` | any refusal or failure | the API's error (`code`, `message` and any extras such as the sandbox lists), the HTTP status, and a plain explanation |

In the connector, the text of a result is the summary followed by the data itself as JSON, so a client that shows the model only the text still gives it every name and identifier; the same data is also sent as structured content. A PDF larger than the inline limit comes back as a description with its size and the advice to read the extraction instead.

### When a call is refused

An `error` result carries the API's code and message, and the connector adds a line telling the assistant what to do next:

| Code | What the assistant is told |
|---|---|
| `MISSING_API_KEY` | No API key was sent. The connector needs the customer’s key. |
| `INVALID_API_KEY` | The API key is not recognised. Check it was copied whole. |
| `API_KEY_REVOKED` | This key was revoked in the developer portal; a new one is needed. |
| `NO_ACCESS` | The account holds no price for this endpoint, so it cannot call it. Support can enable it. |
| `SANDBOX_ONLY` | A test key only works on the sandbox companies and directors. The allowed ones are listed in this error (sandboxCompanies, sandboxDirectors) and by list_sandbox_entities; use one of those, or a live key. |
| `UNLOCK_REQUIRED` | This needs an active company unlock first. unlock_company buys a year of access. |
| `INSUFFICIENT_BALANCE` | The wallet cannot cover this call. Top up in the developer portal. |
| `ALREADY_UNLOCKED` | The company is already unlocked; nothing was charged. |
| `NOTHING_TO_FETCH` | Every listed filing already has its document; nothing to fetch, nothing charged. |
| `RATE_LIMITED` | Too many requests in the last minute. Wait for the Retry-After seconds and try again. |
| `NOT_FOUND` | FileSure does not hold this record. |
| `COMPANY_NOT_FOUND` | FileSure does not hold this company. |
| `INVALID_CIN` | The identifier failed format validation. |
| `INVALID_DIN` | The DIN failed format validation. |
| `DOC_NOT_AVAILABLE` | The document is not on file yet. Check freshness; fetch_documents downloads what is missing. |

### Which form of the key each client uses

| Client | How the connector gets your key | Where it is set up |
|---|---|---|
| Claude.ai and Claude Desktop | sign in with your FileSure account and pick a key; no key in the address | [Connect your AI tool](https://api.filesure.in/reference/start-here/connect-your-ai-tool.md) |
| Claude Code | the key in an `x-api-key` header on the connector address | [Connect your AI tool](https://api.filesure.in/reference/start-here/connect-your-ai-tool.md) |
| Cursor | the key in an `x-api-key` header on the connector address | [Connect your AI tool](https://api.filesure.in/reference/start-here/connect-your-ai-tool.md) |
| Codex | the key in an `x-api-key` header on the connector address | [Connect your AI tool](https://api.filesure.in/reference/start-here/connect-your-ai-tool.md) |
| Anything that can send neither | the keyed address, kept as a fallback | [Connect your AI tool](https://api.filesure.in/reference/start-here/connect-your-ai-tool.md) |

Revoking the key in the developer portal disconnects every tool that used it.

---

## Tool reference

One entry per tool, generated from the definitions the connector serves, in the order the connector lists them. "Rate" is the default rate card for the endpoint behind the tool; negotiated rates apply if your account has them. "Inputs" are what the assistant passes; identifiers are validated with the same rules as the API, so a malformed CIN or DIN is refused before any call.

### list_sandbox_entities

Call this first when the account is on a test key (fsk_test_). Lists every company and director a test key can use: legal name, the brand it is known by, identifier, status, city and state for companies; name and DIN for directors. Free, on test and live keys. On a test key, find_company and find_director search only this set, and any other identifier is refused with SANDBOX_ONLY.

- **Calls:** `GET /v1/sandbox`
- **Rate:** Free
- **Kind:** read-only
- **Results:** `success`, `error`

No inputs.

---

### find_company

Turn a company name (or a CIN, FCIN or LLPIN you are unsure about) into ranked candidates with their identifier, status and registered address. Call this first whenever you only have a name; every other company tool needs the identifier it returns. On a test key it searches only the sandbox companies (see list_sandbox_entities), by legal name or brand. Billed per call at the account’s companies.resolve rate.

- **Calls:** `GET /v1/companies/resolve`
- **Rate:** ₹5 a call (`companies.resolve`)
- **Kind:** read-only
- **Results:** `success`, `error`

| Input | Type | Required | Meaning |
|---|---|---|---|
| `query` | string | yes | Company name, or an exact CIN, FCIN or LLPIN. |
| `state` | string | no | Narrow to a registered state, e.g. Maharashtra. |
| `city` | string | no | Narrow to a registered city. |
| `limit` | integer | no | How many candidates to return, 1 to 20. Default 10. |

---

### get_company

The company’s master data as MCA publishes it: names, status, class, capital, registered address, directors with their roles, and charges. Use for any question about what a company is; use list_filings for what it has filed and get_extraction for financial figures. Billed per call at the account’s companies.master rate. Dates in this record are MM/DD/YYYY.

- **Calls:** `GET /v1/companies/{cin}`
- **Rate:** ₹5 a call (`companies.master`)
- **Kind:** read-only
- **Results:** `success`, `error`

| Input | Type | Required | Meaning |
|---|---|---|---|
| `companyId` | string | yes | Company identifier: CIN, FCIN or LLPIN, as returned by find_company. |
| `idType` | one of `cin`, `fcin`, `llpin` | no | Set only to force tighter validation; auto-detected otherwise. |

---

### list_filings

The list of documents a company has filed with MCA (form, date, category, pages), paginated, with a filingId per row for get_filing_document. This is the index, not the documents. Rows are ordered by when FileSure recorded them, newest first; sort on dateOfFiling (DD/MM/YYYY) yourself for strict date order. Billed per call at the account’s companies.filings.list rate.

- **Calls:** `GET /v1/companies/{cin}/filings`
- **Rate:** ₹5 a call (`companies.filings.list`)
- **Kind:** read-only
- **Results:** `success`, `error`

| Input | Type | Required | Meaning |
|---|---|---|---|
| `companyId` | string | yes | Company identifier: CIN, FCIN or LLPIN, as returned by find_company. |
| `page` | integer | no | Page number, from 1. |
| `limit` | integer | no | Rows per page, up to 200. Default 50. |
| `formId` | string | no | Only this form, e.g. AOC-4, MGT-7, LLP Form 8. |
| `year` | integer | no | Only filings for this calendar year. |
| `documentCategory` | string | no | Only this MCA document category. |

---

### find_director

Turn a person’s name into ranked director candidates with their DIN and current companies. Call this first when you only have a name; get_director needs the DIN it returns. On a test key it searches only the sandbox directors (see list_sandbox_entities). Billed per call at the account’s directors.resolve rate.

- **Calls:** `GET /v1/directors/resolve`
- **Rate:** ₹5 a call (`directors.resolve`)
- **Kind:** read-only
- **Results:** `success`, `error`

| Input | Type | Required | Meaning |
|---|---|---|---|
| `query` | string | yes | Director name, or an exact 8-digit DIN. |
| `limit` | integer | no | How many candidates to return, 1 to 20. Default 10. |

---

### get_director

A director’s profile as MCA holds it (name, nationality, qualification, DIN status) and the companies they are associated with. Phone and email are not here; they sit behind a separate paid contact unlock that this connector does not offer. Billed per call at the account’s directors.profile rate.

- **Calls:** `GET /v1/directors/{din}`
- **Rate:** ₹5 a call (`directors.profile`)
- **Kind:** read-only
- **Results:** `success`, `error`

| Input | Type | Required | Meaning |
|---|---|---|---|
| `din` | string | yes | Director Identification Number, 8 digits, as returned by find_director. |

---

### unlock_company

Buy a year of access to every document this company has filed, in any year, and start the first download; extractions become readable as documents land. This costs money (₹330 by default). Call without confirm to get the account’s price and what it buys; ask the user; then call with confirm: true. Re-unlocking an unlocked company is refused free of charge.

- **Calls:** `POST /v1/companies/{cin}/unlock`
- **Rate:** ₹330 (`companies.unlock`)
- **Kind:** paid action, asks first
- **Results:** `success`, `quote` (without `confirm: true`), `error`

| Input | Type | Required | Meaning |
|---|---|---|---|
| `companyId` | string | yes | Company identifier: CIN, FCIN or LLPIN, as returned by find_company. |
| `confirm` | boolean | no | This action costs money. Leave unset to get the price and what it buys without doing anything; set true, after the user agrees, to run it. |

---

### get_unlock_status

Whether the account holds an active unlock for this company, until when, the price of one if not, and the progress of the document download behind it (pending, in_progress, success). Free. Poll this after unlock_company or fetch_documents to know when documents and extractions are ready.

- **Calls:** `GET /v1/companies/{cin}/unlock`
- **Rate:** Free
- **Kind:** read-only
- **Results:** `success`, `error`

| Input | Type | Required | Meaning |
|---|---|---|---|
| `companyId` | string | yes | Company identifier: CIN, FCIN or LLPIN, as returned by find_company. |

---

### get_filing_document

The PDF of one filing, by the filingId from list_filings. Needs an active unlock (otherwise returns the unlock state, free). Use it only when the user wants the source document; for any figure, prefer get_extraction, which is structured and small. PDFs over 10 MB come back as a description with size and pages instead of bytes. Billed per call at the account’s companies.filings.download rate.

- **Calls:** `GET /v1/companies/{cin}/filings/{filingId}/download`
- **Rate:** 5 paisa a call (`companies.filings.download`)
- **Kind:** read-only
- **Results:** `file` (the PDF), or `success` when no document is returned, `error`

| Input | Type | Required | Meaning |
|---|---|---|---|
| `companyId` | string | yes | Company identifier: CIN, FCIN or LLPIN, as returned by find_company. |
| `filingId` | string | yes | The filingId of a row from list_filings. |

---

### list_extraction_forms

Which form types have structured data extracted for this company (for example AOC-4 financial statements, MGT-7 annual returns, PAS-3 allotments, charges). Start here before get_extraction. Needs an active unlock (otherwise returns the unlock state). Billed per call at the account’s companies.extractions.list rate.

- **Calls:** `GET /v1/companies/{cin}/extractions`
- **Rate:** 5 paisa a call (`companies.extractions.list`)
- **Kind:** read-only
- **Results:** `success`, `error`

| Input | Type | Required | Meaning |
|---|---|---|---|
| `companyId` | string | yes | Company identifier: CIN, FCIN or LLPIN, as returned by find_company. |

---

### list_extraction_years

For one form type, which years have extracted data (for AOC-4 and MGT-7), or the latest snapshot and filings (PAS-3), or the per-charge summaries (charges). Use the formType names from list_extraction_forms. Needs an active unlock. Billed per call at the account’s companies.extractions.years rate.

- **Calls:** `GET /v1/companies/{cin}/extractions/{formType}`
- **Rate:** 5 paisa a call (`companies.extractions.years`)
- **Kind:** read-only
- **Results:** `success`, `error`

| Input | Type | Required | Meaning |
|---|---|---|---|
| `companyId` | string | yes | Company identifier: CIN, FCIN or LLPIN, as returned by find_company. |
| `formType` | string | yes | A form type from list_extraction_forms, e.g. AOC-4. |

---

### get_extraction

The structured data extracted from one filing: balance sheet, profit and loss, shareholding, allotments, and more, as JSON. Use this for any figure or fact from a filing; it is precise and small, unlike the PDF. Pick formType and year from list_extraction_years. Needs an active unlock. Billed per call at the account’s companies.extractions.data rate.

- **Calls:** `GET /v1/companies/{cin}/extractions/{formType}/{year}`
- **Rate:** 5 paisa a call (`companies.extractions.data`)
- **Kind:** read-only
- **Results:** `success`, `error`

| Input | Type | Required | Meaning |
|---|---|---|---|
| `companyId` | string | yes | Company identifier: CIN, FCIN or LLPIN, as returned by find_company. |
| `formType` | string | yes | A form type from list_extraction_forms, e.g. AOC-4. |
| `year` | integer | yes | A year from list_extraction_years. |
| `scope` | one of `standalone`, `consolidated` | no | For financial statements: standalone (default) or consolidated. |

---

### check_freshness

How current FileSure’s copy of this company is: when the record was last refreshed, when the filing list was last read from MCA, how many listed filings have no document on file, whether a refresh is running or still fresh, and the account’s unlock state. Free. Ask this before refresh_company or fetch_documents so you only pay when it is worth it.

- **Calls:** `GET /v1/companies/{cin}/freshness`
- **Rate:** Free
- **Kind:** read-only
- **Results:** `success`, `error`

| Input | Type | Required | Meaning |
|---|---|---|---|
| `companyId` | string | yes | Company identifier: CIN, FCIN or LLPIN, as returned by find_company. |

---

### refresh_company

Re-read this company’s record and filing list from MCA right now: master data, directors, common data and the list of filings. It fetches no documents. One refresh per company per 24 hours is shared by everyone, so inside that window you get the recent result. This costs money (₹1 by default). Call without confirm for the price; then with confirm: true after the user agrees. Use check_freshness first.

- **Calls:** `POST /v1/companies/{cin}/update`
- **Rate:** ₹1 (`companies.update`)
- **Kind:** paid action, asks first
- **Results:** `success`, `quote` (without `confirm: true`), `error`

| Input | Type | Required | Meaning |
|---|---|---|---|
| `companyId` | string | yes | Company identifier: CIN, FCIN or LLPIN, as returned by find_company. |
| `confirm` | boolean | no | This action costs money. Leave unset to get the price and what it buys without doing anything; set true, after the user agrees, to run it. |

---

### fetch_documents

Download the documents an unlocked company is still missing, typically filings made after the unlock. Needs the account’s active unlock; refused free of charge when nothing is missing. This costs money (₹150 by default). Call without confirm for the price; then with confirm: true after the user agrees. check_freshness tells you how many documents are missing.

- **Calls:** `POST /v1/companies/{cin}/documents/fetch`
- **Rate:** ₹150 (`companies.documents.fetch`)
- **Kind:** paid action, asks first
- **Results:** `success`, `quote` (without `confirm: true`), `error`

| Input | Type | Required | Meaning |
|---|---|---|---|
| `companyId` | string | yes | Company identifier: CIN, FCIN or LLPIN, as returned by find_company. |
| `confirm` | boolean | no | This action costs money. Leave unset to get the price and what it buys without doing anything; set true, after the user agrees, to run it. |

---

### get_account

The account’s wallet balance and its usage over the last 30 days, plus the price it pays for every endpoint. Free. Use it to answer "what will this cost me" and "how much is left" before a paid action.

- **Calls:** `GET /v1/account/usage and GET /v1/account/pricing`
- **Rate:** Free
- **Kind:** read-only
- **Results:** `success`, `error`

No inputs.

---

## How FileSure data works

FileSure gives you programmatic access to what the Ministry of Corporate Affairs (MCA) holds on every company, LLP and director in India. Everything the API returns is one of three kinds of thing, and knowing which one you are asking for tells you what it costs and whether you need to unlock anything first.

*Figure: Three kinds of data and the one gate between them.* (https://api.filesure.in/portal/diagrams/data-tiers.svg)

### The register: plain JSON, no unlock

The record MCA keeps on a company or director: name, status, registered address, capital, directors, charges, and the **list** of documents the company has filed. For a director: profile and the companies they sit on. This is what most integrations need, and it is just a call: ₹5, answered from what we hold, returned as JSON.

### Documents: per company, behind an unlock

The filings themselves, as PDFs. MCA charges a fee to hand these over, so we do not hold every PDF for every company in advance. You **unlock** a company once (₹330), we fetch every document it has ever filed from MCA, and you can download any of them for a year. The price is for the whole history, not per year of filings.

*Figure: What an unlock gives you, and for how long.* (https://api.filesure.in/portal/diagrams/unlock-lifecycle.svg)

### Extractions: structured data from those documents

Financial statements, shareholding, charges and other forms, read out of the PDFs into JSON. Extractions come with the unlock: once a company's documents are in, its extractions are queryable too, at 5 paisa a call.

### Time: how current is what we hold?

The register is a copy, and copies age. Three calls deal with that, and they are the only part of the API that costs money without returning data:

- **Freshness check** (free) tells you how old our record is, when the filing list was last read from MCA, and how many listed filings we do not yet hold a PDF for. Ask this first; it tells you whether either of the next two is worth paying for.
- **Refresh** (₹1) re-reads the company's record and filing list from MCA right now. It refreshes the register for everyone, which is why it costs a token ₹1 rather than a price. One refresh per company per 24 hours; if someone refreshed it before you inside that window, you get their result.
- **Fetch new documents** (₹150) downloads the filings that appeared since your unlock. Needs your active unlock; if nothing is missing, it costs nothing.

Four words, used the same way everywhere in this reference: **lookup** (read the register), **unlock** (buy a year of a company's documents), **refresh** (bring its record up to date), **fetch** (download what is missing).

*Figure: The life of one company on your account.* (https://api.filesure.in/portal/diagrams/company-lifecycle.svg)

---

## Quickstart

Everything below runs on a test key against a sandbox company, so it costs nothing. Swap in a live key and the same calls work on any company in India.

**1. Turn a name into a CIN.**

```bash
curl "https://api.filesure.in/v1/companies/resolve?q=cars24" \
  -H "x-api-key: fsk_test_…"
```

```json
{
  "data": { "candidates": [
    { "cin": "U74999HR2015FTC056386", "company": "CARS24 SERVICES PRIVATE LIMITED", "companyStatus": "Active" }
  ] },
  "meta": { "requestId": "…", "priceChargedPaisa": 0, "walletBalanceAfterPaisa": 0 }
}
```

**2. Read the register.**

```bash
curl "https://api.filesure.in/v1/companies/U74999HR2015FTC056386" \
  -H "x-api-key: fsk_test_…"
```

```json
{
  "data": {
    "cin": "U74999HR2015FTC056386",
    "company": "CARS24 SERVICES PRIVATE LIMITED",
    "masterData": {
      "companyData": { "companyStatus": "Active", "dateOfIncorporation": "08/12/2015",
                       "authorisedCapital": 100000000, "paidupCapital": 76934000, "classOfCompany": "Private" },
      "directorData": [ { "DIN": "07347299", "FirstName": "VIKRAM", "LastName": "CHOPRA", "dateOfAppointment": "08/12/2015" } ],
      "indexChargesData": [ { "chName": "HDFC BANK LIMITED", "chargeAmount": 5000000000, "dateOfCreation": "03/15/2022" } ]
    }
  },
  "meta": { "requestId": "…", "priceChargedPaisa": 0, "walletBalanceAfterPaisa": 0 }
}
```

Abridged: the real response carries every field in the MCA record, named exactly as MCA names them.

**3. See what it has filed.**

```bash
curl "https://api.filesure.in/v1/companies/U74999HR2015FTC056386/filings?limit=3" \
  -H "x-api-key: fsk_test_…"
```

```json
{
  "data": [
    { "filingId": "flg_…", "formId": "AOC-4", "dateOfFiling": "28/11/2025", "year": 2025 },
    { "filingId": "flg_…", "formId": "MGT-7", "dateOfFiling": "27/11/2025", "year": 2025 }
  ],
  "meta": { "page": 1, "limit": 3, "total": 654, "requestId": "…" }
}
```

That is the register, and for many integrations it is all you need. The `filingId` on each row is the handle for the PDF behind it; downloading one is where the unlock comes in, and the next page tells you which call to reach for.

---

## Which call do I need?

Three questions, and every path ends at an endpoint:

*Figure: Which call do I need?* (https://api.filesure.in/portal/diagrams/which-call.svg)

Or, as a table:

| You want to… | Call | Needs an unlock? | Cost |
|---|---|---|---|
| See what a test key can use | `GET /v1/sandbox` | No | Free |
| Turn a company name into a CIN | `GET /v1/companies/resolve` | No | ₹5 |
| Get a company's details, directors and charges | `GET /v1/companies/{cin}` | No | ₹5 |
| See what a company has filed (the list, not the PDFs) | `GET /v1/companies/{cin}/filings` | No | ₹5 |
| Turn a director's name into a DIN | `GET /v1/directors/resolve` | No | ₹5 |
| Get a director's profile and companies | `GET /v1/directors/{din}` | No | ₹5 |
| Download a filing PDF | `GET …/filings/{filingId}/download` | Yes, company | 5 paisa |
| Get financials or other extracted data | `GET …/extractions/…` | Yes, company | 5 paisa |
| Open a company's documents for a year | `POST /v1/companies/{cin}/unlock` | Creates one | ₹330 |
| Know whether our copy is current | `GET /v1/companies/{cin}/freshness` | No | Free |
| Bring a company's record up to date | `POST /v1/companies/{cin}/update` | No | ₹1 |
| Download filings made since your unlock | `POST /v1/companies/{cin}/documents/fetch` | Yes, company | ₹150 |
| Get a director's phone and email | `POST /v1/directors/{din}/unlock` then `GET …/contact` | Yes, director | ₹299, then 5 paisa |
| Check your balance and usage, top up | `/v1/account/…` | No | Free |

A typical first integration is three calls: resolve the name, read the master data, list the filings. If you need the PDFs or the numbers inside them, add the unlock. If you keep watching the same companies, add the freshness check and refresh.

---

## Keys and the sandbox

Every request carries your key in the `x-api-key` header. Keys come in two kinds and you can hold several of each:

- **Live keys** (`fsk_live_…`) work on any company or director and are billed against your wallet.
- **Test keys** (`fsk_test_…`) work only on a fixed list of well-known companies and directors, are never billed, and return the same shapes as live keys. `GET /v1/sandbox` lists them. Use them to build and test; switch the key when you go live. A test key outside the list gets `403 SANDBOX_ONLY`, and that error carries the list.

Create and revoke keys from the developer portal. Revoking a key takes effect immediately.

Every key is rate-limited: 60 requests a minute on a live key, 30 on a test key. Past that you get `429 RATE_LIMITED` with a `Retry-After` header and nothing is charged. The refresh has its own, lower ceiling, stated on its page.

Generate keys in the [Developer Portal](https://api.filesure.in/portal/dashboard/keys).

---

## Testing with a test key

A test key never reaches a company outside the sandbox, so the first call is to see what the sandbox holds. Everything below runs on a test key and costs nothing; the same calls work on a live key against any company in India.

1. **See what you can use.** `GET /v1/sandbox` returns the sandbox companies (legal name, the brand each is known by, identifier, status, city and state) and directors (name and DIN).
2. **Find the company.** `GET /v1/companies/resolve?q=zomato` searches only the sandbox on a test key, by legal name or brand, and returns Eternal Limited with its CIN. When nothing matches, the response carries a `hint` with the list's address instead of a live company you could not go on to use.
3. **Read the record.** `GET /v1/companies/{cin}` for the master data, directors and charges.
4. **See what it has filed.** `GET /v1/companies/{cin}/filings` for the filing index; each row carries a `filingId` for the download.
5. **Read the numbers.** `GET /v1/companies/{cin}/extractions` lists the form types with extracted data, `…/extractions/AOC-4` the years, and `…/extractions/AOC-4/{year}` the financial statements as JSON. A test key counts as unlocked on every sandbox company, so these and `GET …/filings/{filingId}/download` answer without an unlock.

In the connector the same chain is `list_sandbox_entities`, `find_company`, `get_company`, `list_filings`, `list_extraction_forms`, `list_extraction_years`, `get_extraction`.

What the set holds: every company has its documents on file and AOC-4 and MGT-7 data, most of them across many years. The two LLPs hold their filed documents but no extractions, because LLPs file neither form. Zepto, incorporated in 2024, has a single year of statements.

A `403 SANDBOX_ONLY` on any call means the identifier is outside the sandbox. The error carries `sandboxCompanies`, `sandboxDirectors` and `nextStep`, so you can pick a working identifier from the response itself.

---

## Billing and the wallet

*Figure: What happens to every request, and where it can be refused for free.* (https://api.filesure.in/portal/diagrams/request-flow.svg)

Your account has a prepaid wallet in rupees. Every billed call deducts its price when it succeeds; a call that fails is never charged, whatever the reason. The response tells you what happened: `meta.priceChargedPaisa` is what the call cost and `meta.walletBalanceAfterPaisa` is what is left, both in paisa (₹1 = 100 paisa).

Prices are per endpoint and per account. The defaults are on the rate card; if your account has negotiated rates, those apply instead. An endpoint your account has no price for returns `403 NO_ACCESS`. That is how access is controlled; there is no separate permission list.

Unlocks are the one purchase that lasts: a company unlock is one year of documents and extractions for that CIN, and every download or extraction inside that year is only the per-call charge. Re-unlocking an already-unlocked company returns `409 ALREADY_UNLOCKED` and charges nothing.

When the wallet cannot cover a call you get `402 INSUFFICIENT_BALANCE` and nothing runs. Top up from the portal or with `POST /v1/account/wallet/recharge`.

---

## Responses and errors

Every response is JSON with the same envelope: `{ data, meta }` on success, `{ error, meta }` on failure. `meta.requestId` is on every response and is also sent as the `X-Request-ID` header; quote it when you write to support.

Errors carry a machine-readable `error.code` and a human `error.message`. A `403 NO_ACCESS` also carries `error.endpoint` and `error.catalogPricePaisa`, the default price of the endpoint you were refused, so you have a number to quote when asking for access. The codes you will meet most:

| Code | Status | Meaning |
|---|---|---|
| `MISSING_API_KEY` / `INVALID_API_KEY` / `API_KEY_REVOKED` | 401 | No key, an unknown key, or a revoked one |
| `INVALID_CIN` / `INVALID_DIN` / `INVALID_ID_TYPE` | 400 | The identifier (or the `idType` query value) failed format validation |
| `NOT_FOUND` / `COMPANY_NOT_FOUND` | 404 | We do not hold that company or director |
| `NO_ACCESS` | 403 | Your account has no price for this endpoint |
| `SANDBOX_ONLY` | 403 | Test key used outside the sandbox; the error lists the sandbox identifiers and a `nextStep` |
| `UNLOCK_REQUIRED` | 403 | This call needs an active unlock first |
| `INSUFFICIENT_BALANCE` | 402 | Wallet cannot cover the call |
| `ALREADY_UNLOCKED` | 409 | You already hold an active unlock |
| `NOTHING_TO_FETCH` | 409 | Every listed filing already has its PDF |
| `RATE_LIMITED` | 429 | Slow down; `Retry-After` says by how much |

Lists are paginated with `?page=` and `?limit=` (default 50, maximum 200). Identifiers are the 21-character CIN, the 6-character FCIN for foreign companies, the 8-character LLPIN for LLPs, and the 8-digit DIN for directors.

Dates arrive as MCA strings and the format depends on the source: company, director and charge records use MM/DD/YYYY (for example `dateOfIncorporation`), while filing records use DD/MM/YYYY (`dateOfFiling`). Each field's description says which. The endpoint examples abbreviate `meta`; the real response always carries `requestId`, and billed calls carry `priceChargedPaisa` and `walletBalanceAfterPaisa` as well.

---

## Support

- **Service status**: [filesure-api.checkly-status-page.com](https://filesure-api.checkly-status-page.com) shows whether the API and the MCP connector are working, with incident updates and uptime history. Subscribe there to hear about incidents by email.
- **Email**: [helpdesk@filesure.in](mailto:helpdesk@filesure.in)
- **Phone**: +91 8104946419
- **Website**: [filesure.in](https://filesure.in)

---

## Sandbox identifiers

Test API keys (`fsk_test_*`) work only on the companies, LLPs and directors
below. Calls return real MCA data with no wallet deduction. Any other
identifier returns `403 SANDBOX_ONLY`, and that error carries these same
lists so a caller can recover without leaving the API. Use them for
integration testing without spending credits.

You do not need to copy this page: `GET /v1/sandbox` returns the same
companies and directors as JSON, free on either key. On a test key the name
searches (`GET /v1/companies/resolve`, `GET /v1/directors/resolve`) look
only at this set, by legal name or by the brand in the "Known as" column.
The flow is written up under [Testing with a test key](https://api.filesure.in/reference/start-here/testing-with-a-test-key.md).

Live keys (`fsk_live_*`) are not restricted and follow each endpoint's
pricing behavior (billed or free, as documented per endpoint).

## Sandbox CINs & LLPINs (52)

| CIN | Company | Known as |
|---|---|---|
| U74999HR2015FTC056386 | CARS24 SERVICES PRIVATE LIMITED | Cars24 |
| U51109KA2012PTC066107 | FLIPKART INTERNET PRIVATE LIMITED | Flipkart |
| U62099KA2013PLC097389 | RAZORPAY SOFTWARE LIMITED | Razorpay |
| L74900KA2015PLC082263 | MEESHO LIMITED | Meesho |
| L33100DL2008PLC178355 | LENSKART SOLUTIONS LIMITED | Lenskart |
| U72200KA2015PTC082063 | SORTING HAT TECHNOLOGIES PRIVATE LIMITED | Unacademy |
| U74900GJ2015PTC107035 | OYO HOTELS AND HOMES PRIVATE LIMITED | OYO |
| U63090GJ2012PLC107088 | ORAVEL STAYS LIMITED | OYO parent, Oravel Stays |
| U93090MH2018PTC308253 | DREAMPLUG TECHNOLOGIES PRIVATE LIMITED | CRED |
| U74900DL2009PTC189166 | RKSV SECURITIES INDIA PRIVATE LIMITED | Upstox |
| U72900KA2016PTC093868 | HIVELOOP TECHNOLOGY PRIVATE LIMITED | Udaan |
| U72900MH2007PTC171875 | SPORTA TECHNOLOGIES PRIVATE LIMITED | Dream11 |
| U74999KA2015PTC103797 | MOHALLA TECH PRIVATE LIMITED | ShareChat |
| U72900KA2011PTC060216 | INMOBI TECHNOLOGY SERVICES PRIVATE LIMITED | InMobi |
| U60100MH2019PLC323444 | API HOLDINGS LIMITED | PharmEasy |
| U72900KA2010PTC086596 | ANI TECHNOLOGIES PRIVATE LIMITED | Ola Cabs |
| L40100KA2013PLC093769 | ATHER ENERGY LIMITED | Ather Energy |
| U52210TG2015PTC097115 | ROPPEN TRANSPORTATION SERVICES PRIVATE LIMITED | Rapido |
| U72900KA2011PTC060958 | VEDANTU INNOVATIONS PRIVATE LIMITED | Vedantu |
| U74999TN2016PTC176669 | CUREFIT HEALTHCARE PRIVATE LIMITED | Cult.fit |
| U51101MH2011PTC224903 | MANASH LIFESTYLE PRIVATE LIMITED | Purplle |
| U52300MH2013PLC249758 | IMAGINE MARKETING LIMITED | boAt |
| U74900KA2014PTC077652 | NOBROKER TECHNOLOGIES SOLUTIONS PRIVATE LIMITED | NoBroker |
| L74140DL2014PLC274413 | URBAN COMPANY LIMITED | Urban Company |
| U74999DL2018PTC331205 | RESILIENT INNOVATIONS PRIVATE LIMITED | BharatPe |
| U74110KA2016PTC120161 | ACKO TECHNOLOGY & SERVICES PRIVATE LIMITED | Acko |
| U74999KA2018FTC113333 | GALACTUS FUNWARE TECHNOLOGY PRIVATE LIMITED | MPL |
| U74140MH2019PTC328769 | AMICA FINANCIAL TECHNOLOGIES PRIVATE LIMITED | Jupiter |
| U80902MH2012PTC258559 | UPGRAD EDUCATION PRIVATE LIMITED | upGrad |
| U24299DL2021PTC380760 | GLOBALBEES BRANDS PRIVATE LIMITED | GlobalBees |
| U66000MH2013PTC249565 | TURTLEMINT INSURANCE BROKING SERVICES PRIVATE LIMITED | Turtlemint |
| U74999MH2012PTC237035 | LEADERSHIP BOULEVARD PRIVATE LIMITED | LEAD School |
| U74130KA2010PTC052192 | INNOVATIVE RETAIL CONCEPTS PRIVATE LIMITED | BigBasket |
| U51909KA2011PTC060707 | SUPERMARKET GROCERY SUPPLIES PRIVATE LIMITED | BigBasket supply arm |
| U62099KA2024PTC194937 | KIRANAKART SOFTWARE SOLUTIONS PRIVATE LIMITED | Zepto |
| U65999DL2019FTC353020 | PINE LABS FINANCE PRIVATE LIMITED | Pine Labs |
| U74900KA2015PTC080321 | DELIGHTFUL GOURMET PRIVATE LIMITED | Licious |
| U28100KA2020PTC135505 | ZETWERK FABPLUS PRIVATE LIMITED | Zetwerk |
| U74900TG2015PTC101793 | DARWINBOX DIGITAL SOLUTIONS PRIVATE LIMITED | Darwinbox |
| U72900DL2018PTC331409 | POSTMAN MEDIA PRIVATE LIMITED | Postman |
| U74140GJ2015PLC154393 | OFB TECH LIMITED | OfBusiness |
| U65990DL2022PTC401899 | OXYZO FINVEST PRIVATE LIMITED | Oxyzo |
| U72900TN2020PTC137251 | CREDAVENUE PRIVATE LIMITED | Yubi, formerly CredAvenue |
| U67200KA2017PTC166507 | OPEN FINANCIAL TECHNOLOGIES PRIVATE LIMITED | Open |
| U72900KA2015PTC080871 | GARAGEPRENEURS INTERNET PRIVATE LIMITED | slice |
| L93030DL2010PLC198141 | ETERNAL LIMITED | Eternal, formerly Zomato |
| L74110KA2013PLC096530 | SWIGGY LIMITED | Swiggy |
| L52600MH2012PLC230136 | FSN E-COMMERCE VENTURES LIMITED | Nykaa |
| L72200DL2000PLC108985 | ONE 97 COMMUNICATIONS LIMITED | Paytm |
| L63090DL2011PLC221234 | DELHIVERY LIMITED | Delhivery |
| ACK-2998 | SUGEE TWENTY SEVEN DEVELOPERS LLP |  |
| ACX-7976 | ZALPE FOOD & BEVERAGES LLP |  |

## Sandbox DINs (451)

Derived from the directors of the sandbox CINs above.

| DIN | DIN | DIN | DIN | DIN | DIN |
|---|---|---|---|---|---|
| 00002157 | 00002615 | 00002803 | 00003423 | 00003633 | 00003882 |
| 00004223 | 00004771 | 00006486 | 00007347 | 00008886 | 00010499 |
| 00012214 | 00012870 | 00013580 | 00017880 | 00017944 | 00018234 |
| 00022157 | 00024141 | 00031034 | 00036043 | 00037022 | 00040491 |
| 00040789 | 00046081 | 00054553 | 00056826 | 00058105 | 00059201 |
| 00059877 | 00062650 | 00065640 | 00067073 | 00074964 | 00108347 |
| 00109854 | 00118188 | 00118324 | 00125058 | 00133351 | 00162957 |
| 00177699 | 00187429 | 00222708 | 00253613 | 00272372 | 00281547 |
| 00307229 | 00322784 | 00337276 | 00361030 | 00381741 | 00394065 |
| 00405142 | 00466521 | 00507827 | 00508259 | 00521511 | 00555052 |
| 00570124 | 00644360 | 00677638 | 00677965 | 00706336 | 00754512 |
| 00766821 | 00863123 | 00871445 | 01049871 | 01096264 | 01099294 |
| 01113742 | 01164185 | 01173669 | 01237902 | 01243445 | 01338251 |
| 01338477 | 01384344 | 01388140 | 01432123 | 01449885 | 01461055 |
| 01469375 | 01494407 | 01592796 | 01653176 | 01679598 | 01730685 |
| 01755822 | 01797971 | 01802995 | 01827653 | 01837379 | 01874769 |
| 01893686 | 01902890 | 01913013 | 01930079 | 01947911 | 02005518 |
| 02014353 | 02040991 | 02046291 | 02057007 | 02069428 | 02070081 |
| 02092948 | 02102783 | 02122751 | 02124077 | 02126100 | 02131404 |
| 02132315 | 02144558 | 02159016 | 02175753 | 02181034 | 02227607 |
| 02242466 | 02249682 | 02339751 | 02356492 | 02376801 | 02442753 |
| 02466181 | 02470016 | 02499607 | 02528942 | 02590433 | 02613583 |
| 02670178 | 02741174 | 02748363 | 02844650 | 02848515 | 02853367 |
| 02853403 | 02870609 | 02945481 | 02968574 | 02993708 | 03024803 |
| 03090626 | 03090814 | 03098172 | 03103474 | 03118947 | 03145392 |
| 03172733 | 03258070 | 03266967 | 03284823 | 03287473 | 03328890 |
| 03341028 | 03399650 | 03404629 | 03430136 | 03431848 | 03440936 |
| 03441515 | 03450221 | 03488061 | 03523267 | 03534101 | 03545900 |
| 03549431 | 03559152 | 03565167 | 03566737 | 03579584 | 03579776 |
| 03581311 | 03584898 | 03604399 | 03605392 | 03617181 | 05002534 |
| 05014753 | 05116855 | 05131571 | 05132272 | 05132286 | 05138366 |
| 05169635 | 05177838 | 05185378 | 05186193 | 05192249 | 05195656 |
| 05223910 | 05244077 | 05251806 | 05277865 | 05318899 | 05323714 |
| 05323737 | 05325285 | 05325741 | 05328267 | 05336659 | 05341082 |
| 06364184 | 06371682 | 06392463 | 06449636 | 06454495 | 06502272 |
| 06512080 | 06527810 | 06549915 | 06552579 | 06556746 | 06557158 |
| 06557679 | 06575810 | 06594510 | 06610582 | 06618646 | 06652017 |
| 06659730 | 06660799 | 06661731 | 06663764 | 06666246 | 06672135 |
| 06680073 | 06682759 | 06686145 | 06732021 | 06735472 | 06754654 |
| 06764019 | 06794418 | 06796621 | 06798956 | 06824179 | 06848801 |
| 06891864 | 06912294 | 06940578 | 06946611 | 06998824 | 06999772 |
| 07002169 | 07005029 | 07005033 | 07005253 | 07013113 | 07018743 |
| 07018744 | 07019019 | 07031462 | 07031464 | 07082038 | 07106615 |
| 07107975 | 07121539 | 07121802 | 07129633 | 07135817 | 07168514 |
| 07197443 | 07202923 | 07203452 | 07206780 | 07209950 | 07219194 |
| 07221836 | 07225910 | 07238872 | 07245972 | 07248661 | 07248672 |
| 07251075 | 07254037 | 07298703 | 07304038 | 07312305 | 07315528 |
| 07318865 | 07323472 | 07333270 | 07337772 | 07339751 | 07339752 |
| 07406331 | 07434021 | 07439364 | 07485688 | 07505290 | 07517101 |
| 07553913 | 07582619 | 07596310 | 07630166 | 07634689 | 07639288 |
| 07661578 | 07696873 | 07720350 | 07736862 | 07756379 | 07767248 |
| 07779526 | 07806792 | 07820090 | 07825610 | 07847243 | 07868696 |
| 07878167 | 07929995 | 07931382 | 07948982 | 07955350 | 07972892 |
| 07984221 | 07986644 | 08006199 | 08073534 | 08087425 | 08090416 |
| 08090417 | 08113520 | 08137143 | 08154941 | 08166016 | 08174465 |
| 08178251 | 08189873 | 08222884 | 08223390 | 08225312 | 08225313 |
| 08239898 | 08277445 | 08284722 | 08303261 | 08343545 | 08351358 |
| 08354909 | 08355220 | 08383621 | 08407641 | 08417798 | 08501575 |
| 08505775 | 08507514 | 08524150 | 08658846 | 08661466 | 08682099 |
| 08712047 | 08736307 | 08742229 | 08743508 | 08776136 | 08780334 |
| 08780335 | 08808558 | 08821475 | 08839209 | 08908841 | 08935969 |
| 08950500 | 08959036 | 09043859 | 09075331 | 09092519 | 09114153 |
| 09129636 | 09136934 | 09155801 | 09166446 | 09196992 | 09218485 |
| 09247644 | 09258341 | 09298721 | 09365919 | 09367772 | 09376632 |
| 09389414 | 09398202 | 09408470 | 09431299 | 09434542 | 09440372 |
| 09471450 | 09475452 | 09490014 | 09500698 | 09521316 | 09577436 |
| 09577495 | 09580591 | 09588432 | 09632942 | 09637916 | 09660723 |
| 09748791 | 09749539 | 09813415 | 09817635 | 10041633 | 10044673 |
| 10049059 | 10056096 | 10061648 | 10090589 | 10105558 | 10197152 |
| 10209423 | 10214230 | 10237124 | 10243913 | 10411559 | 10427117 |
| 10462333 | 10475712 | 10511184 | 10511270 | 10589911 | 10593910 |
| 10656028 | 10712707 | 10720049 | 10775163 | 10939877 | 11056907 |
| 11061694 | 11077148 | 11086018 | 11116635 | 11222871 | 11304281 |
| 11335707 | 11382912 | 11544170 | 11544199 | 11583385 | 11611722 |
| 11620355 | 11632627 | 11692470 | 11692471 | 11692472 | 11745292 |
| 11767043 |

---

## Endpoints

### Sandbox identifiers

Test API keys (`fsk_test_*`) work only on the companies, LLPs and directors
below. Calls return real MCA data with no wallet deduction. Any other
identifier returns `403 SANDBOX_ONLY`, and that error carries these same
lists so a caller can recover without leaving the API. Use them for
integration testing without spending credits.

You do not need to copy this page: `GET /v1/sandbox` returns the same
companies and directors as JSON, free on either key. On a test key the name
searches (`GET /v1/companies/resolve`, `GET /v1/directors/resolve`) look
only at this set, by legal name or by the brand in the "Known as" column.
The flow is written up under [Testing with a test key](https://api.filesure.in/reference/start-here/testing-with-a-test-key.md).

Live keys (`fsk_live_*`) are not restricted and follow each endpoint's
pricing behavior (billed or free, as documented per endpoint).

## Sandbox CINs & LLPINs (52)

| CIN | Company | Known as |
|---|---|---|
| U74999HR2015FTC056386 | CARS24 SERVICES PRIVATE LIMITED | Cars24 |
| U51109KA2012PTC066107 | FLIPKART INTERNET PRIVATE LIMITED | Flipkart |
| U62099KA2013PLC097389 | RAZORPAY SOFTWARE LIMITED | Razorpay |
| L74900KA2015PLC082263 | MEESHO LIMITED | Meesho |
| L33100DL2008PLC178355 | LENSKART SOLUTIONS LIMITED | Lenskart |
| U72200KA2015PTC082063 | SORTING HAT TECHNOLOGIES PRIVATE LIMITED | Unacademy |
| U74900GJ2015PTC107035 | OYO HOTELS AND HOMES PRIVATE LIMITED | OYO |
| U63090GJ2012PLC107088 | ORAVEL STAYS LIMITED | OYO parent, Oravel Stays |
| U93090MH2018PTC308253 | DREAMPLUG TECHNOLOGIES PRIVATE LIMITED | CRED |
| U74900DL2009PTC189166 | RKSV SECURITIES INDIA PRIVATE LIMITED | Upstox |
| U72900KA2016PTC093868 | HIVELOOP TECHNOLOGY PRIVATE LIMITED | Udaan |
| U72900MH2007PTC171875 | SPORTA TECHNOLOGIES PRIVATE LIMITED | Dream11 |
| U74999KA2015PTC103797 | MOHALLA TECH PRIVATE LIMITED | ShareChat |
| U72900KA2011PTC060216 | INMOBI TECHNOLOGY SERVICES PRIVATE LIMITED | InMobi |
| U60100MH2019PLC323444 | API HOLDINGS LIMITED | PharmEasy |
| U72900KA2010PTC086596 | ANI TECHNOLOGIES PRIVATE LIMITED | Ola Cabs |
| L40100KA2013PLC093769 | ATHER ENERGY LIMITED | Ather Energy |
| U52210TG2015PTC097115 | ROPPEN TRANSPORTATION SERVICES PRIVATE LIMITED | Rapido |
| U72900KA2011PTC060958 | VEDANTU INNOVATIONS PRIVATE LIMITED | Vedantu |
| U74999TN2016PTC176669 | CUREFIT HEALTHCARE PRIVATE LIMITED | Cult.fit |
| U51101MH2011PTC224903 | MANASH LIFESTYLE PRIVATE LIMITED | Purplle |
| U52300MH2013PLC249758 | IMAGINE MARKETING LIMITED | boAt |
| U74900KA2014PTC077652 | NOBROKER TECHNOLOGIES SOLUTIONS PRIVATE LIMITED | NoBroker |
| L74140DL2014PLC274413 | URBAN COMPANY LIMITED | Urban Company |
| U74999DL2018PTC331205 | RESILIENT INNOVATIONS PRIVATE LIMITED | BharatPe |
| U74110KA2016PTC120161 | ACKO TECHNOLOGY & SERVICES PRIVATE LIMITED | Acko |
| U74999KA2018FTC113333 | GALACTUS FUNWARE TECHNOLOGY PRIVATE LIMITED | MPL |
| U74140MH2019PTC328769 | AMICA FINANCIAL TECHNOLOGIES PRIVATE LIMITED | Jupiter |
| U80902MH2012PTC258559 | UPGRAD EDUCATION PRIVATE LIMITED | upGrad |
| U24299DL2021PTC380760 | GLOBALBEES BRANDS PRIVATE LIMITED | GlobalBees |
| U66000MH2013PTC249565 | TURTLEMINT INSURANCE BROKING SERVICES PRIVATE LIMITED | Turtlemint |
| U74999MH2012PTC237035 | LEADERSHIP BOULEVARD PRIVATE LIMITED | LEAD School |
| U74130KA2010PTC052192 | INNOVATIVE RETAIL CONCEPTS PRIVATE LIMITED | BigBasket |
| U51909KA2011PTC060707 | SUPERMARKET GROCERY SUPPLIES PRIVATE LIMITED | BigBasket supply arm |
| U62099KA2024PTC194937 | KIRANAKART SOFTWARE SOLUTIONS PRIVATE LIMITED | Zepto |
| U65999DL2019FTC353020 | PINE LABS FINANCE PRIVATE LIMITED | Pine Labs |
| U74900KA2015PTC080321 | DELIGHTFUL GOURMET PRIVATE LIMITED | Licious |
| U28100KA2020PTC135505 | ZETWERK FABPLUS PRIVATE LIMITED | Zetwerk |
| U74900TG2015PTC101793 | DARWINBOX DIGITAL SOLUTIONS PRIVATE LIMITED | Darwinbox |
| U72900DL2018PTC331409 | POSTMAN MEDIA PRIVATE LIMITED | Postman |
| U74140GJ2015PLC154393 | OFB TECH LIMITED | OfBusiness |
| U65990DL2022PTC401899 | OXYZO FINVEST PRIVATE LIMITED | Oxyzo |
| U72900TN2020PTC137251 | CREDAVENUE PRIVATE LIMITED | Yubi, formerly CredAvenue |
| U67200KA2017PTC166507 | OPEN FINANCIAL TECHNOLOGIES PRIVATE LIMITED | Open |
| U72900KA2015PTC080871 | GARAGEPRENEURS INTERNET PRIVATE LIMITED | slice |
| L93030DL2010PLC198141 | ETERNAL LIMITED | Eternal, formerly Zomato |
| L74110KA2013PLC096530 | SWIGGY LIMITED | Swiggy |
| L52600MH2012PLC230136 | FSN E-COMMERCE VENTURES LIMITED | Nykaa |
| L72200DL2000PLC108985 | ONE 97 COMMUNICATIONS LIMITED | Paytm |
| L63090DL2011PLC221234 | DELHIVERY LIMITED | Delhivery |
| ACK-2998 | SUGEE TWENTY SEVEN DEVELOPERS LLP |  |
| ACX-7976 | ZALPE FOOD & BEVERAGES LLP |  |

## Sandbox DINs (451)

Derived from the directors of the sandbox CINs above.

| DIN | DIN | DIN | DIN | DIN | DIN |
|---|---|---|---|---|---|
| 00002157 | 00002615 | 00002803 | 00003423 | 00003633 | 00003882 |
| 00004223 | 00004771 | 00006486 | 00007347 | 00008886 | 00010499 |
| 00012214 | 00012870 | 00013580 | 00017880 | 00017944 | 00018234 |
| 00022157 | 00024141 | 00031034 | 00036043 | 00037022 | 00040491 |
| 00040789 | 00046081 | 00054553 | 00056826 | 00058105 | 00059201 |
| 00059877 | 00062650 | 00065640 | 00067073 | 00074964 | 00108347 |
| 00109854 | 00118188 | 00118324 | 00125058 | 00133351 | 00162957 |
| 00177699 | 00187429 | 00222708 | 00253613 | 00272372 | 00281547 |
| 00307229 | 00322784 | 00337276 | 00361030 | 00381741 | 00394065 |
| 00405142 | 00466521 | 00507827 | 00508259 | 00521511 | 00555052 |
| 00570124 | 00644360 | 00677638 | 00677965 | 00706336 | 00754512 |
| 00766821 | 00863123 | 00871445 | 01049871 | 01096264 | 01099294 |
| 01113742 | 01164185 | 01173669 | 01237902 | 01243445 | 01338251 |
| 01338477 | 01384344 | 01388140 | 01432123 | 01449885 | 01461055 |
| 01469375 | 01494407 | 01592796 | 01653176 | 01679598 | 01730685 |
| 01755822 | 01797971 | 01802995 | 01827653 | 01837379 | 01874769 |
| 01893686 | 01902890 | 01913013 | 01930079 | 01947911 | 02005518 |
| 02014353 | 02040991 | 02046291 | 02057007 | 02069428 | 02070081 |
| 02092948 | 02102783 | 02122751 | 02124077 | 02126100 | 02131404 |
| 02132315 | 02144558 | 02159016 | 02175753 | 02181034 | 02227607 |
| 02242466 | 02249682 | 02339751 | 02356492 | 02376801 | 02442753 |
| 02466181 | 02470016 | 02499607 | 02528942 | 02590433 | 02613583 |
| 02670178 | 02741174 | 02748363 | 02844650 | 02848515 | 02853367 |
| 02853403 | 02870609 | 02945481 | 02968574 | 02993708 | 03024803 |
| 03090626 | 03090814 | 03098172 | 03103474 | 03118947 | 03145392 |
| 03172733 | 03258070 | 03266967 | 03284823 | 03287473 | 03328890 |
| 03341028 | 03399650 | 03404629 | 03430136 | 03431848 | 03440936 |
| 03441515 | 03450221 | 03488061 | 03523267 | 03534101 | 03545900 |
| 03549431 | 03559152 | 03565167 | 03566737 | 03579584 | 03579776 |
| 03581311 | 03584898 | 03604399 | 03605392 | 03617181 | 05002534 |
| 05014753 | 05116855 | 05131571 | 05132272 | 05132286 | 05138366 |
| 05169635 | 05177838 | 05185378 | 05186193 | 05192249 | 05195656 |
| 05223910 | 05244077 | 05251806 | 05277865 | 05318899 | 05323714 |
| 05323737 | 05325285 | 05325741 | 05328267 | 05336659 | 05341082 |
| 06364184 | 06371682 | 06392463 | 06449636 | 06454495 | 06502272 |
| 06512080 | 06527810 | 06549915 | 06552579 | 06556746 | 06557158 |
| 06557679 | 06575810 | 06594510 | 06610582 | 06618646 | 06652017 |
| 06659730 | 06660799 | 06661731 | 06663764 | 06666246 | 06672135 |
| 06680073 | 06682759 | 06686145 | 06732021 | 06735472 | 06754654 |
| 06764019 | 06794418 | 06796621 | 06798956 | 06824179 | 06848801 |
| 06891864 | 06912294 | 06940578 | 06946611 | 06998824 | 06999772 |
| 07002169 | 07005029 | 07005033 | 07005253 | 07013113 | 07018743 |
| 07018744 | 07019019 | 07031462 | 07031464 | 07082038 | 07106615 |
| 07107975 | 07121539 | 07121802 | 07129633 | 07135817 | 07168514 |
| 07197443 | 07202923 | 07203452 | 07206780 | 07209950 | 07219194 |
| 07221836 | 07225910 | 07238872 | 07245972 | 07248661 | 07248672 |
| 07251075 | 07254037 | 07298703 | 07304038 | 07312305 | 07315528 |
| 07318865 | 07323472 | 07333270 | 07337772 | 07339751 | 07339752 |
| 07406331 | 07434021 | 07439364 | 07485688 | 07505290 | 07517101 |
| 07553913 | 07582619 | 07596310 | 07630166 | 07634689 | 07639288 |
| 07661578 | 07696873 | 07720350 | 07736862 | 07756379 | 07767248 |
| 07779526 | 07806792 | 07820090 | 07825610 | 07847243 | 07868696 |
| 07878167 | 07929995 | 07931382 | 07948982 | 07955350 | 07972892 |
| 07984221 | 07986644 | 08006199 | 08073534 | 08087425 | 08090416 |
| 08090417 | 08113520 | 08137143 | 08154941 | 08166016 | 08174465 |
| 08178251 | 08189873 | 08222884 | 08223390 | 08225312 | 08225313 |
| 08239898 | 08277445 | 08284722 | 08303261 | 08343545 | 08351358 |
| 08354909 | 08355220 | 08383621 | 08407641 | 08417798 | 08501575 |
| 08505775 | 08507514 | 08524150 | 08658846 | 08661466 | 08682099 |
| 08712047 | 08736307 | 08742229 | 08743508 | 08776136 | 08780334 |
| 08780335 | 08808558 | 08821475 | 08839209 | 08908841 | 08935969 |
| 08950500 | 08959036 | 09043859 | 09075331 | 09092519 | 09114153 |
| 09129636 | 09136934 | 09155801 | 09166446 | 09196992 | 09218485 |
| 09247644 | 09258341 | 09298721 | 09365919 | 09367772 | 09376632 |
| 09389414 | 09398202 | 09408470 | 09431299 | 09434542 | 09440372 |
| 09471450 | 09475452 | 09490014 | 09500698 | 09521316 | 09577436 |
| 09577495 | 09580591 | 09588432 | 09632942 | 09637916 | 09660723 |
| 09748791 | 09749539 | 09813415 | 09817635 | 10041633 | 10044673 |
| 10049059 | 10056096 | 10061648 | 10090589 | 10105558 | 10197152 |
| 10209423 | 10214230 | 10237124 | 10243913 | 10411559 | 10427117 |
| 10462333 | 10475712 | 10511184 | 10511270 | 10589911 | 10593910 |
| 10656028 | 10712707 | 10720049 | 10775163 | 10939877 | 11056907 |
| 11061694 | 11077148 | 11086018 | 11116635 | 11222871 | 11304281 |
| 11335707 | 11382912 | 11544170 | 11544199 | 11583385 | 11611722 |
| 11620355 | 11632627 | 11692470 | 11692471 | 11692472 | 11745292 |
| 11767043 |

#### List the sandbox companies and directors

`GET /v1/sandbox`

Group: Sandbox identifiers. Page: https://api.filesure.in/reference/list-sandbox-entities.md

**What it returns**

Every company and director a test key can use. For companies: the legal name, the brand it is known by (`knownAs`, `null` when there is none), the identifier and its type, status, city and state, sorted by name. For directors: name and DIN, sorted by DIN. The same lists appear in the "Sandbox identifiers" section of this reference and inside every `403 SANDBOX_ONLY` error.

**Billing**

Free on test and live keys. Nothing is written to your usage.

**Sandbox behavior**

This is the sandbox. On a test key, call it first: `GET /v1/companies/resolve` and `GET /v1/directors/resolve` search only what it lists, and every other endpoint refuses identifiers that are not here.

**Common errors**

- `401 MISSING_API_KEY` / `INVALID_API_KEY`: no key, or an unknown one

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/sandbox" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** The sandbox companies and directors

*Two of each (the real response carries the whole set)*

```json
{
  "data": {
    "companies": [
      {
        "cin": "U74999HR2015FTC056386",
        "company": "CARS24 SERVICES PRIVATE LIMITED",
        "knownAs": "Cars24",
        "idType": "cin",
        "companyStatus": "Active",
        "city": "Gurugram",
        "state": "Haryana"
      },
      {
        "cin": "L93030DL2010PLC198141",
        "company": "ETERNAL LIMITED",
        "knownAs": "Eternal, formerly Zomato",
        "idType": "cin",
        "companyStatus": "Active",
        "city": "NEW DELHI",
        "state": "Delhi"
      }
    ],
    "directors": [
      {
        "din": "11692470",
        "fullName": "RAHUL MANIKRAO ZALPE"
      },
      {
        "din": "11692472",
        "fullName": "NILESH KASHINATH HIWALE"
      }
    ]
  },
  "meta": {
    "companies": 52,
    "directors": 451,
    "requestId": "…"
  }
}
```

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

### Look up the register

The record MCA holds on a company or director, as plain JSON. Resolve a name to an identifier, read master data, directors and charges, or list what a company has filed. ₹5 a call, no unlock needed.

#### Resolve company name to CIN

`GET /v1/companies/resolve`

Group: Look up the register. Page: https://api.filesure.in/reference/resolve-company.md

**What it returns**

Ranked CIN candidates for a free-text company name (or a single hit when `q` is already a valid CIN/FCIN/LLPIN). Each candidate carries inline disambiguation fields — registered address, status, incorporation date, current directors/promoters, and NIC/activity code — plus a Typesense `matchScore` (higher = better).

Optional `state` and `city` query filters narrow results to companies whose registered address matches.

**Billing**

Billed per call at your `companies.resolve` rate (see the [rate card](https://api.filesure.in/pricing.html)).

**Sandbox behavior**

Test keys (`fsk_test_*`) are free and search only the sandbox companies: by legal name, by the brand the company is known by, or by exact identifier; `state` and `city` still filter. The response carries `sandbox: true`, and when nothing matches, a `hint` pointing at `GET /v1/sandbox`. A company outside the sandbox is never returned to a test key, because every other endpoint would then refuse it.

**Common errors**

- `400 MISSING_QUERY` — `q` (or `name`) is required
- `503 SEARCH_UNAVAILABLE` — name search requires Typesense; exact CIN lookups still work

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `q` | query | no | string | Company name or exact CIN/FCIN/LLPIN. Alias `name` is also accepted. |
| `name` | query | no | string | Alias for `q`. |
| `state` | query | no | string | Filter by registered state (e.g. `Maharashtra`). |
| `city` | query | no | string | Filter by registered city. |
| `limit` | query | no | integer | Maximum number of candidates to return. (default 10, 1 to 20) |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/companies/resolve?q=cars24&limit=3" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** Ranked resolve results (may be an empty `candidates` array)

Fields:

- `data`: object
  - `query`: string
  - `candidates`: array of object
    - `cin`: string
    - `company`: string
    - `idType`: string (`cin`, `fcin`, `llpin`)
    - `companyStatus`: string, optional
    - `dateOfIncorporation`: string, optional. MM/DD/YYYY string as MCA returns it. Every date in company, director and charge records uses this format; filing records use DD/MM/YYYY.
    - `registeredAddress`: object, optional
    - `nicCode`: string, optional
    - `mainDivisionDescription`: string, optional
    - `directors`: array of object
    - `matchScore`: number. Typesense relevance score (higher = better match)
  - `sandbox`: boolean, optional. Present and `true` on a test key, whose search covers only the sandbox.
  - `hint`: string, optional. On a test key with no match, where the sandbox identifiers are listed.
- `meta`: object
  - `requestId`: string, optional
  - `priceChargedPaisa`: integer, optional
  - `walletBalanceAfterPaisa`: integer, optional

**400** Request validation failed (invalid identifier, malformed query param, etc.)

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

**402** Wallet balance is below the endpoint price

```json
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient wallet balance. Please recharge.",
    "balancePaisa": 0,
    "requiredPaisa": 500
  }
}
```

**403** No pricing assigned for this endpoint (live key), or the account is disabled. A test key is never refused here: its search is scoped to the sandbox instead (see `sandbox` and `hint` in the response), so `SANDBOX_ONLY` does not occur.

*No pricing record (live key)*

```json
{
  "error": {
    "code": "NO_ACCESS",
    "message": "No access to endpoint 'companies.resolve'. Contact support to enable access.",
    "endpoint": "companies.resolve",
    "catalogPricePaisa": 500
  }
}
```

*Customer account deactivated*

```json
{
  "error": {
    "code": "ACCOUNT_DISABLED",
    "message": "Your account has been disabled. Contact support."
  }
}
```

**503** Name search backend unavailable

#### Get company master data

`GET /v1/companies/{cin}`

Group: Look up the register. Page: https://api.filesure.in/reference/get-company-master.md

**What it returns**

The full MCA master-data packet for a company:

- `companyData`: the MCA master record (registration, type/category/class, capital, status, dates, registered/correspondence addresses)
- `commonData`: MCA's supplementary record (NIC industry codes, AGM date, balance-sheet date). May be `null` if it has not been fetched yet
- `directorData[]`: the directors of this company. Rows deduped by DIN; `MCAUserRole[]` arrays merged, with a small drop list applied
- `indexChargesData[]`: charges (mortgages) on this company, verbatim. Empty `[]` is common (most companies have none)

Fields are surfaced **as MCA returns them** (camelCase, British spellings like `authorisedCapital`, PascalCase charge addresses); fields are only ever dropped, never renamed. The one addition: the three capital amounts (`paidUpCapital`, `authorisedCapital`, `subscribedCapital`) each carry readable companions beside the raw number — a `…Formatted` compact form (e.g. `₹7.69 Cr`) and a `…Display` full form with Indian digit grouping (e.g. `₹7,69,34,000`). The raw integers are unchanged; the ₹ sign carries the currency. **Address filtering:** only `Registered Address` and `Correspondence Address` are kept; auxiliary address types are dropped. Identifiers supported: 21-char **CIN**, 6-char **FCIN** (foreign), 8-char **LLPIN**. The `?idType=` query param is optional; auto-detect handles all three.

**Billing**

Billed per call against your INR wallet at the rate in your pricing row for this endpoint.

**Sandbox behavior**

Test keys (`fsk_test_*`) work freely on sandbox-whitelisted CINs/LLPINs (no wallet deduction). Outside the whitelist, test keys return `403 SANDBOX_ONLY`.

**Common errors**

- `400 INVALID_CIN` — identifier failed CIN/FCIN/LLPIN format validation
- `404` — company not found in our cache. The unlock endpoint won't help here either — it requires the CIN to already be in master data. If you need a specific CIN added (or you suspect ours is stale relative to MCA), contact [helpdesk@filesure.in](mailto:helpdesk@filesure.in).

Plus the global auth/wallet/permission errors — see the [error codes table](https://api.filesure.in/reference/start-here/responses-and-errors.md).

**See also**

- [List company filings](https://api.filesure.in/reference/list-company-filings.md)
- [List extracted form types](https://api.filesure.in/reference/list-extractions.md)
- [Unlock a company](https://api.filesure.in/reference/unlock-company.md)

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `cin` | path | yes | string | Company identifier. One of three formats — accepted on `/v1/companies/:cin`: - **CIN** — 21-character Indian Corporate Identification Number (e.g., U72900PB2022PTC055860) - **FCIN** — 6-character Foreign Company Identification Number (e.g., F07030) - **LLPIN** — 8-character LLP Identification Number (e.g., AAA-1234) Pair with the optional `?idType=cin\|fcin\|llpin` query param for stricter validation; auto-detect when omitted. Test keys (`fsk_test_*`) can only call identifiers in the **Sandbox** allowlist — see the Sandbox tag in the sidebar for the full list of 50 sample CINs and 2 LLPINs. |
| `idType` | query | no | string (`cin`, `fcin`, `llpin`) | Optional. Tighter validation when set; auto-detect when omitted. |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/companies/U74999HR2015FTC056386" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** Master data found

*Sandbox CIN — CARS24 (registered company)*

```json
{
  "data": {
    "cin": "U74999HR2015FTC056386",
    "company": "CARS24 SERVICES PRIVATE LIMITED",
    "cinHistory": [],
    "nameHistory": [],
    "masterData": {
      "companyData": {
        "cin": "U74999HR2015FTC056386",
        "companyName": "CARS24 SERVICES PRIVATE LIMITED",
        "companyType": "Company limited by Shares",
        "companyOrigin": "Indian Non-Government Company",
        "companyCategory": "Company limited by Shares",
        "companySubcategory": "Non-government company",
        "classOfCompany": "Private",
        "dateOfIncorporation": "08/12/2015",
        "authorisedCapital": 100000000,
        "paidupCapital": 76934000,
        "numberOfMembers": "0",
        "activeCompliance": "ACTIVE compliant",
        "companyStatus": "Active",
        "whetherListedOrNot": "Unlisted",
        "MCAMDSCompanyAddress": [
          {
            "addressType": "Registered Address",
            "streetAddress": "Plot No. 78, Sector 44, Gurugram, Haryana, 122001",
            "country": "India"
          }
        ]
      },
      "commonData": {
        "mainDivisionCode": "74",
        "mainDivisionDescription": "Other professional, scientific and technical activities",
        "companyAddress": [
          {
            "addressType": "Registered Address",
            "streetAddress": "Plot No. 78, Sector 44, Gurugram, Haryana, 122001"
          }
        ]
      },
      "directorData": [
        {
          "DIN": "07347299",
          "PAN": "ABCPK1234E",
          "FirstName": "VIKRAM",
          "LastName": "CHOPRA",
          "dateOfAppointment": "08/12/2015",
          "DirectorDisqualified": "false",
          "MCAUserRole": [
            {
              "role": "Director",
              "designation": "Director",
              "cin": "U74999HR2015FTC056386",
              "kmpFlag": "false"
            }
          ]
        }
      ],
      "indexChargesData": [
        {
          "chargeId": "100123456",
          "chName": "HDFC BANK LIMITED",
          "chargeAmount": 5000000000,
          "dateOfCreation": "03/15/2022",
          "dateOfModification": null,
          "dateOfSatisfaction": null,
          "StreetAddress": "HDFC Bank House, Senapati Bapat Marg, Lower Parel, Mumbai",
          "City": "Mumbai",
          "State": "Maharashtra",
          "PostalCode": "400013",
          "Country": "India"
        }
      ]
    }
  },
  "meta": {
    "requestId": "…",
    "createdAt": "2023-04-12T07:18:32.444Z",
    "updatedAt": "2026-04-28T03:21:09.001Z"
  }
}
```

*Sandbox LLPIN — shape demo*

```json
{
  "data": {
    "cin": "ACK-2998",
    "company": "SUGEE TWENTY SEVEN DEVELOPERS LLP",
    "cinHistory": [],
    "nameHistory": [],
    "masterData": {
      "companyData": {
        "cin": "ACK-2998",
        "companyName": "SUGEE TWENTY SEVEN DEVELOPERS LLP",
        "companyType": "Limited Liability Partnership",
        "dateOfIncorporation": "11/11/2024",
        "numberOfPartners": "2",
        "numberOfDesignatedPartners": "2",
        "companyStatus": "Active"
      },
      "commonData": null,
      "directorData": null,
      "indexChargesData": []
    }
  },
  "meta": {
    "requestId": "…",
    "createdAt": "2023-08-22T14:12:08.901Z",
    "updatedAt": "2026-04-15T11:42:30.004Z"
  }
}
```

**400** Identifier failed format validation, or unknown idType value

*Identifier doesn't match CIN/FCIN/LLPIN format*

```json
{
  "error": {
    "code": "INVALID_CIN",
    "message": "The provided identifier failed format validation. Expected CIN, FCIN, or LLPIN."
  }
}
```

*Unknown idType query value*

```json
{
  "error": {
    "code": "INVALID_ID_TYPE",
    "message": "Unknown idType. Valid values: cin, fcin, llpin."
  }
}
```

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

**402** Wallet balance is below the endpoint price

```json
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient wallet balance. Please recharge.",
    "balancePaisa": 0,
    "requiredPaisa": 500
  }
}
```

**403** No pricing assigned, or test key tried to access non-sandbox CIN/DIN

*No pricing record (live key)*

```json
{
  "error": {
    "code": "NO_ACCESS",
    "message": "No access to endpoint 'companies.master'. Contact support to enable access.",
    "endpoint": "companies.master",
    "catalogPricePaisa": 500
  }
}
```

*Test key outside sandbox whitelist*

```json
{
  "error": {
    "code": "SANDBOX_ONLY",
    "message": "A test key only works on the sandbox companies and directors. They are listed in this response and at GET /v1/sandbox. Use one of those, or a live key.",
    "sandboxCompanies": [
      {
        "cin": "U74999HR2015FTC056386",
        "company": "CARS24 SERVICES PRIVATE LIMITED",
        "knownAs": "Cars24"
      },
      {
        "cin": "L93030DL2010PLC198141",
        "company": "ETERNAL LIMITED",
        "knownAs": "Eternal, formerly Zomato"
      }
    ],
    "sandboxDirectors": [
      {
        "din": "11692472",
        "fullName": "NILESH KASHINATH HIWALE"
      }
    ],
    "nextStep": "GET /v1/sandbox"
  }
}
```

**404** Resource not found in master data

#### List company filings

`GET /v1/companies/{cin}/filings`

Group: Look up the register. Page: https://api.filesure.in/reference/list-company-filings.md

**What it returns**

Paginated list of MCA filings for this company (offset-based, default `limit=50`, max `200`). Filterable by `formId` (e.g. `MGT-7`, `LLP Form 8`, `AOC-4 XBRL`), `year`, and `documentCategory`. Each row carries MCA fields verbatim — `formId`, `documentCategory`, `dateOfFiling` (DD/MM/YYYY string), `fileSize`, `fileType`, `numberOfPages`, etc. Each row also carries an opaque `filingId` token (`flg_…`); pass it as the path param to the download endpoint. The MCA `documentCode` is deliberately not surfaced. Rows are ordered by when we recorded them, newest first; that usually follows the filing date but is not guaranteed, so sort on `dateOfFiling` yourself when strict date order matters.

Date-range filtering is not supported (because `dateOfFiling` is stored as a DD/MM/YYYY string). Use `?year=` to narrow by calendar year.

**Billing**

Billed per call. The list itself is just metadata — the actual PDF retrieval is a separate unlock-gated download per filing.

**Sandbox behavior**

Test keys (`fsk_test_*`) work freely on sandbox-whitelisted CINs/LLPINs. Real filings list returned, no wallet deduction. Outside the whitelist: `403 SANDBOX_ONLY`.

**Common errors**

- `400 INVALID_CIN` — identifier failed CIN/FCIN/LLPIN format validation
- `400 INVALID_ID_TYPE` — `?idType=` set to a value outside the enum

Plus the global auth/wallet/permission errors — see the [error codes table](https://api.filesure.in/reference/start-here/responses-and-errors.md).

**See also**

- [Get company master data](https://api.filesure.in/reference/get-company-master.md)
- [Download filing PDF](https://api.filesure.in/reference/download-filing.md)
- [Unlock a company](https://api.filesure.in/reference/unlock-company.md) (required before PDFs are downloadable)

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `cin` | path | yes | string | Company identifier. One of three formats — accepted on `/v1/companies/:cin`: - **CIN** — 21-character Indian Corporate Identification Number (e.g., U72900PB2022PTC055860) - **FCIN** — 6-character Foreign Company Identification Number (e.g., F07030) - **LLPIN** — 8-character LLP Identification Number (e.g., AAA-1234) Pair with the optional `?idType=cin\|fcin\|llpin` query param for stricter validation; auto-detect when omitted. Test keys (`fsk_test_*`) can only call identifiers in the **Sandbox** allowlist — see the Sandbox tag in the sidebar for the full list of 50 sample CINs and 2 LLPINs. |
| `idType` | query | no | string (`cin`, `fcin`, `llpin`) | Optional. Tighter validation when set; auto-detect when omitted. `INVALID_ID_TYPE` 400 when set to anything outside the enum. |
| `page` | query | no | integer | (default 1, 1) |
| `limit` | query | no | integer | (default 50, 1 to 200) |
| `formId` | query | no | string | Exact match against the MCA `formId` field. |
| `year` | query | no | integer | Exact match against the integer `year` field on the filing doc. |
| `documentCategory` | query | no | string | Exact match against the MCA `documentCategory` field. |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/companies/U74999HR2015FTC056386/filings?limit=3" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** Paginated list of filings (empty `data` array if the company has no filings or doesn't exist).

*Sandbox CIN — first 3 filings (truncated)* Real CARS24 has 653 filings; example shows the first 3 of page 1. Pagination uses `meta.page`, `meta.limit`, `meta.total`, `meta.totalPages`.

```json
{
  "data": [
    {
      "filingId": "flg_Ui2a1vItyyFYoAGGmefipN0RoT9EtmjHQz4KfzMeVE",
      "formId": "AOC-4",
      "documentCategory": "Annual Returns and Balance Sheet eForms",
      "attachmentLabel": "AOC-4",
      "dateOfFiling": "30/09/2024",
      "year": 2024,
      "fileSize": 412050,
      "fileType": "pdf",
      "numberOfPages": 24,
      "description": null,
      "createdAt": "2024-10-01T03:14:22.000Z",
      "updatedAt": "2024-10-01T03:14:22.000Z"
    },
    {
      "filingId": "flg_eK4hXp82mZQyaBcDeFgHiJkLmNoPqRsTuVwXyZ",
      "formId": "MGT-7",
      "documentCategory": "Annual Returns and Balance Sheet eForms",
      "attachmentLabel": "MGT-7",
      "dateOfFiling": "30/09/2024",
      "year": 2024,
      "fileSize": 318220,
      "fileType": "pdf",
      "numberOfPages": 18,
      "description": null,
      "createdAt": "2024-10-01T03:14:25.000Z",
      "updatedAt": "2024-10-01T03:14:25.000Z"
    },
    {
      "filingId": "flg_Q3vRtY8nWxZpLkMjNbVcXdSeFhJuKiOoPaSdF",
      "formId": "CHG-9",
      "documentCategory": "Charge Documents",
      "attachmentLabel": "optional_attachment",
      "dateOfFiling": "30/09/2021",
      "year": 2021,
      "fileSize": 636790,
      "fileType": "pdf",
      "numberOfPages": 36,
      "description": null,
      "createdAt": "2021-10-02T11:48:09.000Z",
      "updatedAt": "2021-10-02T11:48:09.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 653,
    "totalPages": 33
  }
}
```

*Company with no filings*

```json
{
  "data": [],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 0,
    "totalPages": 0
  }
}
```

**400** Request validation failed (invalid identifier, malformed query param, etc.)

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

**402** Wallet balance is below the endpoint price

```json
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient wallet balance. Please recharge.",
    "balancePaisa": 0,
    "requiredPaisa": 500
  }
}
```

**403** No pricing assigned, or test key tried to access non-sandbox CIN/DIN

*No pricing record (live key)*

```json
{
  "error": {
    "code": "NO_ACCESS",
    "message": "No access to endpoint 'companies.master'. Contact support to enable access.",
    "endpoint": "companies.master",
    "catalogPricePaisa": 500
  }
}
```

*Test key outside sandbox whitelist*

```json
{
  "error": {
    "code": "SANDBOX_ONLY",
    "message": "A test key only works on the sandbox companies and directors. They are listed in this response and at GET /v1/sandbox. Use one of those, or a live key.",
    "sandboxCompanies": [
      {
        "cin": "U74999HR2015FTC056386",
        "company": "CARS24 SERVICES PRIVATE LIMITED",
        "knownAs": "Cars24"
      },
      {
        "cin": "L93030DL2010PLC198141",
        "company": "ETERNAL LIMITED",
        "knownAs": "Eternal, formerly Zomato"
      }
    ],
    "sandboxDirectors": [
      {
        "din": "11692472",
        "fullName": "NILESH KASHINATH HIWALE"
      }
    ],
    "nextStep": "GET /v1/sandbox"
  }
}
```

#### Resolve director name to DIN

`GET /v1/directors/resolve`

Group: Look up the register. Page: https://api.filesure.in/reference/resolve-director.md

**What it returns**

Ranked DIN candidates for a free-text director name (or a single hit when `q` is already an 8-digit DIN). Each candidate includes status, associated company names, directorship count, and a Typesense `matchScore`.

**Billing**

Billed per call at your `directors.resolve` rate (see the [rate card](https://api.filesure.in/pricing.html)).

**Sandbox behavior**

Test keys (`fsk_test_*`) are free and search only the sandbox directors, by name or exact DIN. The response carries `sandbox: true`, and when nothing matches, a `hint` pointing at `GET /v1/sandbox`.

**Common errors**

- `400 MISSING_QUERY` — `q` (or `name`) is required
- `503 SEARCH_UNAVAILABLE` — name search requires Typesense; exact DIN lookups still work

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `q` | query | no | string | Director name or exact 8-digit DIN. Alias `name` is also accepted. |
| `name` | query | no | string | Alias for `q`. |
| `limit` | query | no | integer | Maximum number of candidates to return. (default 10, 1 to 20) |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/directors/resolve?q=cars24&limit=3" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** Ranked resolve results (may be an empty `candidates` array)

Fields:

- `data`: object
  - `query`: string
  - `candidates`: array of object
    - `din`: string
    - `fullName`: string, optional
    - `status`: string, optional
    - `dinAllocationDate`: string, optional
    - `personType`: string, optional
    - `companies`: array of string
    - `totalDirectorshipCount`: integer
    - `matchScore`: number
  - `sandbox`: boolean, optional. Present and `true` on a test key, whose search covers only the sandbox.
  - `hint`: string, optional. On a test key with no match, where the sandbox identifiers are listed.
- `meta`: object
  - `requestId`: string, optional
  - `priceChargedPaisa`: integer, optional
  - `walletBalanceAfterPaisa`: integer, optional

**400** Request validation failed (invalid identifier, malformed query param, etc.)

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

**402** Wallet balance is below the endpoint price

```json
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient wallet balance. Please recharge.",
    "balancePaisa": 0,
    "requiredPaisa": 500
  }
}
```

**403** No pricing assigned for this endpoint (live key), or the account is disabled. A test key is never refused here: its search is scoped to the sandbox instead (see `sandbox` and `hint` in the response), so `SANDBOX_ONLY` does not occur.

*No pricing record (live key)*

```json
{
  "error": {
    "code": "NO_ACCESS",
    "message": "No access to endpoint 'companies.resolve'. Contact support to enable access.",
    "endpoint": "companies.resolve",
    "catalogPricePaisa": 500
  }
}
```

*Customer account deactivated*

```json
{
  "error": {
    "code": "ACCOUNT_DISABLED",
    "message": "Your account has been disabled. Contact support."
  }
}
```

**503** Name search backend unavailable

#### Get director profile

`GET /v1/directors/{din}`

Group: Look up the register. Page: https://api.filesure.in/reference/get-director-master.md

**What it returns**

The director's identity (DIN, name), the verbatim MCA `companyData[]` array (the per-company role records MCA returns for a DIN) and `mcaSignatoryCessationMasterHistory[]`, the appointment/cessation ledger for past company roles (each row: `cin`, `accountName`, `designation`, `appointmentDate`, `cessationDate`, and usually `accountStatus`). Use history when `companyData[]` is empty or lacks cessation dates.

Each `companyData[]` row carries MCA-shaped fields (`ucin`, `cin_LLPIN`, `nameOfTheCompany`, `role`, `designation`, `directorFlag`, `companyStatus`, `roleEffectiveDate`, `cessationDate`, plus LLP-specific contribution fields and body-corporate metadata).

Contact-tier fields are deliberately **excluded** here — query [GET /v1/directors/{din}/contact](https://api.filesure.in/reference/get-director-contact.md) for those (separate unlock):

`pan`, `aadhaarNumber`, `mobileNumber`, `emailAddress`, `passportNumber`, `dob`, `birthPlace`, `drivingLicenseNumber`, `votersIdNumber`, `addresses`, `fathersFirstName`/`Middle`/`Last`. Dropped both at the top level and within each `companyData[]` and `mcaSignatoryCessationMasterHistory[]` row.

Per-row drops (both arrays): FileSure/MCA-internal IDs (`accountId`, `userId`, `userName`, `approverId`, `companyId`, `srn`, `v2UserId`, `bodyCorpInsideIndiaId`, `bodyCorpOutsideIndiaId`), duplicates of top-level director identity (`din` — always the DIN in the path, returned once as `data.din` — plus `firstName`, `middleName`, `lastName`, `gender`, `nationality`, `educationalQualification`), operational flags (`flagged`, `oldFlag`). Everything else passes through verbatim — MCA naming, no flattened display structures.

**Billing**

Billed per call.

**Sandbox behavior**

Test keys (`fsk_test_*`) work freely on sandbox-whitelisted DINs. Outside the whitelist: `403 SANDBOX_ONLY`.

**Common errors**

- `400 INVALID_DIN` — DIN failed 8-digit format validation
- `404` — director not found in our cache

Plus the global auth/wallet/permission errors — see the [error codes table](https://api.filesure.in/reference/start-here/responses-and-errors.md).

**See also**

- [Get director contact](https://api.filesure.in/reference/get-director-contact.md) (unlock-gated; PII fields)
- [Unlock director's contact](https://api.filesure.in/reference/unlock-director-contact.md)
- [Get company master data](https://api.filesure.in/reference/get-company-master.md)

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `din` | path | yes | string | 8-digit Director Identification Number (DIN). Test keys (`fsk_test_*`) can only call DINs in the **Sandbox** allowlist — see the Sandbox tag in the sidebar for the full list. |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/directors/00002157" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** Director master data

*Sandbox DIN — 1 company role (truncated)* Real directors typically sit on 2–10 companies; example shows 1 representative `companyData[]` row.

```json
{
  "data": {
    "din": "00002157",
    "firstName": "AJAY",
    "lastName": "VERMA",
    "gender": "MALE",
    "nationality": "India",
    "educationalQualification": "Graduate",
    "companyData": [
      {
        "ucin": "U74999HR2015FTC056386",
        "cin_LLPIN": "U74999HR2015FTC056386",
        "nameOfTheCompany": "CARS24 SERVICES PRIVATE LIMITED",
        "role": "Director",
        "designation": "Director",
        "directorFlag": "true",
        "companyStatus": "Active",
        "roleEffectiveDate": "2015-02-02",
        "cessationDate": null
      }
    ]
  },
  "meta": {
    "updatedAt": "2026-04-15T11:42:30.004Z",
    "source": "MCA"
  }
}
```

**400** DIN failed format validation (must be 8 numeric digits)

```json
{
  "error": {
    "code": "INVALID_DIN",
    "message": "DIN must be 8 numeric digits."
  }
}
```

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

**402** Wallet balance is below the endpoint price

```json
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient wallet balance. Please recharge.",
    "balancePaisa": 0,
    "requiredPaisa": 500
  }
}
```

**403** No pricing assigned, or test key tried to access non-sandbox CIN/DIN

*No pricing record (live key)*

```json
{
  "error": {
    "code": "NO_ACCESS",
    "message": "No access to endpoint 'companies.master'. Contact support to enable access.",
    "endpoint": "companies.master",
    "catalogPricePaisa": 500
  }
}
```

*Test key outside sandbox whitelist*

```json
{
  "error": {
    "code": "SANDBOX_ONLY",
    "message": "A test key only works on the sandbox companies and directors. They are listed in this response and at GET /v1/sandbox. Use one of those, or a live key.",
    "sandboxCompanies": [
      {
        "cin": "U74999HR2015FTC056386",
        "company": "CARS24 SERVICES PRIVATE LIMITED",
        "knownAs": "Cars24"
      },
      {
        "cin": "L93030DL2010PLC198141",
        "company": "ETERNAL LIMITED",
        "knownAs": "Eternal, formerly Zomato"
      }
    ],
    "sandboxDirectors": [
      {
        "din": "11692472",
        "fullName": "NILESH KASHINATH HIWALE"
      }
    ],
    "nextStep": "GET /v1/sandbox"
  }
}
```

**404** No director found for the given DIN

```json
{
  "error": {
    "code": "DIRECTOR_NOT_FOUND",
    "message": "No director found for DIN 12345678."
  }
}
```

### Documents and financials

The filing PDFs and the data extracted from them. Unlock a company once (₹330 for every document it has filed, in any year; access lasts one year) and the first download runs; then download any filing and read any extraction for 5 paisa a call. Filings made after the unlock are picked up under Keep a company current.

#### Unlock a company

`POST /v1/companies/{cin}/unlock`

Group: Documents and financials. Page: https://api.filesure.in/reference/unlock-company.md

**What it returns**

On a live key with an active pricing row: `202 Accepted` with the freshly-created unlock record (1-year expiry). The `data.job` field is `null` immediately after the POST — the background refresh job hasn't been registered yet. Poll [GET /v1/companies/{cin}/unlock](https://api.filesure.in/reference/get-company-unlock.md) seconds later and the response will carry a populated `job` object whose `processingStages` track the asynchronous download + extraction. On a `fsk_test_*` key with a sandbox-whitelisted CIN: `200 OK` with a synthetic unlock and `job: null` — no real writes, no MCA fetch.

**What happens next.** The unlock starts the first document download. Poll [GET /v1/companies/{cin}/unlock](https://api.filesure.in/reference/get-company-unlock.md) for progress (`processingStages.documentDownloadV3.status` goes `pending` → `in_progress` → `success`); downloads and extractions work as documents land, and the window lasts one year. How the unlock relates to the refresh and the document fetch is explained in [How FileSure data works](https://api.filesure.in/reference/start-here/how-filesure-data-works.md).

**Idempotency:** repeating this on a CIN with an active unlock returns `409 ALREADY_UNLOCKED` with the existing unlock's expiry; no double charge.

**Billing**

Pay-gate. Charges the company-unlock fee from your wallet up front: your `companies.unlock` rate (see the [rate card](https://api.filesure.in/pricing.html)). Wallet must have sufficient balance; otherwise `402 INSUFFICIENT_BALANCE` with no unlock created.

**Sandbox behavior**

`fsk_test_*` keys on a sandbox-whitelisted CIN return `200 OK` with a synthetic unlock (`{ unlocked: true, sandbox: true, job: null }`) and skip all real writes / MCA fetches. Test keys on non-sandbox CINs return `403 SANDBOX_ONLY`.

**Common errors**

- `400 INVALID_CIN` — CIN/FCIN/LLPIN format validation failed
- `402 INSUFFICIENT_BALANCE` — wallet under the unlock price
- `403 NO_ACCESS` — no pricing row for `companies.unlock`
- `403 SANDBOX_ONLY` — test key on a non-sandbox CIN
- `404` — CIN not in our master-data cache
- `409 ALREADY_UNLOCKED` — unlock already exists; no double charge

Plus the global auth/wallet/permission errors — see the [error codes table](https://api.filesure.in/reference/start-here/responses-and-errors.md).

**See also**

- [Cascade diagram](https://api.filesure.in/reference/start-here/how-filesure-data-works.md) (visual: POST → wallet deduct → background refresh → filings/extractions queryable)
- [Get unlock status](https://api.filesure.in/reference/get-company-unlock.md) (poll job progress + grab zip URLs)
- [Download filing PDF](https://api.filesure.in/reference/download-filing.md)
- [Get extracted data](https://api.filesure.in/reference/get-extraction-data.md)

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `cin` | path | yes | string | 21-character Corporate Identification Number (CIN). |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/companies/U74999HR2015FTC056386/unlock" \
  -X POST \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** Sandbox synthetic unlock (test key on a sandbox CIN).

*Test key on a sandbox CIN — synthetic unlock (no real writes)*

```json
{
  "data": {
    "cin": "U74999HR2015FTC056386",
    "unlocked": true,
    "unlockedAt": null,
    "expiresAt": null,
    "sandbox": true,
    "job": null
  },
  "meta": {}
}
```

**202** Unlock created; download + extraction job queued.

*Live key — unlock created, job queued (job materialises seconds later)* Right after POST, `data.job` is `null` because the background refresh hasn't been registered yet. Poll [GET /v1/companies/{cin}/unlock](https://api.filesure.in/reference/get-company-unlock.md) to see job progress once it has materialised.

```json
{
  "data": {
    "cin": "U74999HR2015FTC056386",
    "unlocked": true,
    "unlockedAt": "2026-05-01T07:30:00.000Z",
    "expiresAt": "2027-05-01T07:30:00.000Z",
    "unlockPrice": 33000,
    "job": null
  },
  "meta": {}
}
```

**400** Identifier failed format validation, or unknown idType value

*Identifier doesn't match CIN/FCIN/LLPIN format*

```json
{
  "error": {
    "code": "INVALID_CIN",
    "message": "The provided identifier failed format validation. Expected CIN, FCIN, or LLPIN."
  }
}
```

*Unknown idType query value*

```json
{
  "error": {
    "code": "INVALID_ID_TYPE",
    "message": "Unknown idType. Valid values: cin, fcin, llpin."
  }
}
```

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

**402** Wallet balance is below the endpoint price

```json
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient wallet balance. Please recharge.",
    "balancePaisa": 0,
    "requiredPaisa": 500
  }
}
```

**403** `NO_ACCESS` (no pricing record) or `SANDBOX_ONLY` (test key on non-sandbox CIN).

*Customer has no pricing for companies.unlock*

```json
{
  "error": {
    "code": "NO_ACCESS",
    "message": "No access to endpoint 'companies.unlock'. Contact support to enable access.",
    "endpoint": "companies.unlock",
    "catalogPricePaisa": 33000
  }
}
```

*Test key on a non-sandbox CIN*

```json
{
  "error": {
    "code": "SANDBOX_ONLY",
    "message": "A test key only works on the sandbox companies and directors. They are listed in this response and at GET /v1/sandbox. Use one of those, or a live key.",
    "sandboxCompanies": [
      {
        "cin": "U74999HR2015FTC056386",
        "company": "CARS24 SERVICES PRIVATE LIMITED",
        "knownAs": "Cars24"
      },
      {
        "cin": "L93030DL2010PLC198141",
        "company": "ETERNAL LIMITED",
        "knownAs": "Eternal, formerly Zomato"
      }
    ],
    "sandboxDirectors": [
      {
        "din": "11692472",
        "fullName": "NILESH KASHINATH HIWALE"
      }
    ],
    "nextStep": "GET /v1/sandbox"
  }
}
```

**404** CIN passed format validation but is not present in our master data.

**

```json
{
  "error": {
    "code": "NOT_FOUND",
    "message": "No company found for CIN U99999XX2020XYZ999999."
  }
}
```

**409** Active unlock already exists for this CIN. No double charge.

#### Get unlock status

`GET /v1/companies/{cin}/unlock`

Group: Documents and financials. Page: https://api.filesure.in/reference/get-company-unlock.md

**What it returns**

Unlock state and live job progress for this CIN. The same envelope is used regardless of state. Three branches:

- **Active unlock:** `unlocked: true`, `unlockedAt`, `expiresAt`, plus a `job` object carrying live progress from the background refresh. The `processingStages.documentDownloadV3.status` field is the primary progress signal (`pending` → `in_progress` → `success`, usually within minutes of the unlock POST). When download is complete, `documentDownloadV3` also surfaces `zipFiles[]` — direct download URLs to per-batch zip archives of the company's PDFs (use these instead of bulk-download).
- **No unlock:** `unlocked: false`, `unlockPrice` (or `null` if your customer has no pricing for `companies.unlock`).
- **Sandbox** (test key + sandbox CIN): synthetic `unlocked: true, sandbox: true, job: null`. No real reads or writes.

Read-only — does not advance the cascade or write to the refresh job.

**Billing**

Free. No wallet deduction; not subject to pricing rows.

**Sandbox behavior**

Test keys (`fsk_test_*`) on a sandbox-whitelisted CIN return the synthetic branch above. Outside the whitelist: `403 SANDBOX_ONLY`.

**Common errors**

- `400 INVALID_CIN` — CIN/FCIN/LLPIN format validation failed

Plus the global auth/permission errors — see the [error codes table](https://api.filesure.in/reference/start-here/responses-and-errors.md).

**See also**

- [Cascade diagram](https://api.filesure.in/reference/start-here/how-filesure-data-works.md) (visual: where each `processingStages.*` step sits in the pipeline)
- [Unlock a company](https://api.filesure.in/reference/unlock-company.md) (start the cascade)
- [Download filing PDF](https://api.filesure.in/reference/download-filing.md)

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `cin` | path | yes | string | 21-character Corporate Identification Number (CIN). |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/companies/U74999HR2015FTC056386/unlock" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** Unlock state for this CIN (any of the three branches above).

*Unlocked, download stage complete (with zip URLs)* When `documentDownloadV3.status` reaches `success`, `zipFiles[]` carries direct download URLs — fetch the bundled PDFs without iterating over individual filing IDs.

```json
{
  "data": {
    "cin": "U74999HR2015FTC056386",
    "unlocked": true,
    "unlockedAt": "2026-05-01T07:30:00.000Z",
    "expiresAt": "2027-05-01T07:30:00.000Z",
    "unlockPrice": 33000,
    "job": {
      "id": "67ef88c3a9b1c2d3e4f56789",
      "processingStages": {
        "documentDownloadV3": {
          "status": "success",
          "lastUpdated": "2026-05-01T04:40:08.074Z",
          "totalZipFiles": 2,
          "zipFiles": [
            {
              "filename": "U74999HR2015FTC056386_documents_20260501_043919_batch_1.zip",
              "container": "zip-files",
              "blob_url": "https://mcavpd.blob.core.windows.net/zip-files/U74999HR2015FTC056386_documents_20260501_043919_batch_1.zip"
            },
            {
              "filename": "U74999HR2015FTC056386_documents_20260501_043947_batch_2.zip",
              "container": "zip-files",
              "blob_url": "https://mcavpd.blob.core.windows.net/zip-files/U74999HR2015FTC056386_documents_20260501_043947_batch_2.zip"
            }
          ]
        },
        "financials": {
          "status": "success"
        },
        "financialExTriggered": true
      },
      "createdAt": "2026-05-01T04:30:00.500Z",
      "updatedAt": "2026-05-01T04:40:08.074Z"
    }
  },
  "meta": {}
}
```

*Unlocked, download stage still running*

```json
{
  "data": {
    "cin": "U74999HR2015FTC056386",
    "unlocked": true,
    "unlockedAt": "2026-05-01T07:30:00.000Z",
    "expiresAt": "2027-05-01T07:30:00.000Z",
    "unlockPrice": 33000,
    "job": {
      "id": "67ef88c3a9b1c2d3e4f56789",
      "processingStages": {
        "documentDownloadV3": {
          "status": "in_progress",
          "lastUpdated": "2026-05-01T07:33:00.000Z"
        }
      },
      "createdAt": "2026-05-01T07:30:00.500Z",
      "updatedAt": "2026-05-01T07:33:00.000Z"
    }
  },
  "meta": {}
}
```

*Customer hasn't unlocked this CIN*

```json
{
  "data": {
    "cin": "U74999HR2015FTC056386",
    "unlocked": false,
    "unlockPrice": 33000,
    "job": null
  },
  "meta": {}
}
```

**400** Identifier failed format validation, or unknown idType value

*Identifier doesn't match CIN/FCIN/LLPIN format*

```json
{
  "error": {
    "code": "INVALID_CIN",
    "message": "The provided identifier failed format validation. Expected CIN, FCIN, or LLPIN."
  }
}
```

*Unknown idType query value*

```json
{
  "error": {
    "code": "INVALID_ID_TYPE",
    "message": "Unknown idType. Valid values: cin, fcin, llpin."
  }
}
```

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

**403** Test key on a non-sandbox CIN.

#### Download filing PDF

`GET /v1/companies/{cin}/filings/{filingId}/download`

Group: Documents and financials. Page: https://api.filesure.in/reference/download-filing.md

**What it returns**

The actual PDF binary stream when the company is unlocked and the document has been downloaded into our cache. Otherwise returns a `200` JSON unlock-status payload (Content-Type `application/json`) with `{ unlocked: false, unlockPrice }`. PDFs stream from object storage; the API picks the correct backend per CIN. `filingId` is the opaque `flg_…` token from the [list endpoint](https://api.filesure.in/reference/list-company-filings.md); the underlying MCA `documentCode` is not surfaced.

**Billing**

Unlock-gated. Needs an active company unlock for this CIN, plus the per-call download fee; inside the unlock's year every download is just that fee. Without an active unlock, this endpoint returns the unlock-status JSON instead of the file (no charge). What an unlock covers: [How FileSure data works](https://api.filesure.in/reference/start-here/how-filesure-data-works.md).

**Sandbox behavior**

Test keys (`fsk_test_*`) on a sandbox-whitelisted CIN return a synthetic unlock state. The PDF returned is the real cached file when available, or the unlock-status JSON; no wallet deduction. Outside the sandbox: `403 SANDBOX_ONLY`.

**Common errors**

- `400 INVALID_CIN` — CIN/FCIN/LLPIN format validation failed
- `400 INVALID_FILING_ID` — token not in `flg_…` format or failed integrity check
- `404 DOC_NOT_AVAILABLE` — filing exists in our index but the PDF isn't downloaded yet. Right after an unlock, wait for the download job (watch `GET /v1/companies/{cin}/unlock`). If the unlock finished long ago and the filing is newer, `POST /v1/companies/{cin}/documents/fetch` (₹150) downloads it; `GET /v1/companies/{cin}/freshness` (free) shows how many are missing. `POST /v1/companies/{cin}/update` does **not** fetch PDFs — it refreshes the record and the filing list only

Plus the global auth/wallet/permission errors — see the [error codes table](https://api.filesure.in/reference/start-here/responses-and-errors.md).

**See also**

- [List company filings](https://api.filesure.in/reference/list-company-filings.md) (where `filingId` comes from)
- [Unlock a company](https://api.filesure.in/reference/unlock-company.md)
- [Get unlock status](https://api.filesure.in/reference/get-company-unlock.md)

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `cin` | path | yes | string | Company identifier. One of three formats — accepted on `/v1/companies/:cin`: - **CIN** — 21-character Indian Corporate Identification Number (e.g., U72900PB2022PTC055860) - **FCIN** — 6-character Foreign Company Identification Number (e.g., F07030) - **LLPIN** — 8-character LLP Identification Number (e.g., AAA-1234) Pair with the optional `?idType=cin\|fcin\|llpin` query param for stricter validation; auto-detect when omitted. Test keys (`fsk_test_*`) can only call identifiers in the **Sandbox** allowlist — see the Sandbox tag in the sidebar for the full list of 50 sample CINs and 2 LLPINs. |
| `filingId` | path | yes | string | Opaque filing identifier from the list endpoint. |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/companies/U74999HR2015FTC056386/filings/<filingId from the filings list>/download" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** PDF binary stream (when unlocked) OR unlock-status JSON (when not unlocked — Content-Type `application/json`).

*Customer hasn't unlocked this CIN yet* Returned with HTTP 200 and Content-Type `application/json` — no wallet deduction. Direct the customer to the unlock endpoint.

```json
{
  "data": {
    "unlocked": false,
    "unlockPrice": 33000
  },
  "meta": {}
}
```

**400** Request validation failed (invalid identifier, malformed query param, etc.)

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

**403** `SANDBOX_ONLY` — test key used outside the sandbox whitelist. Note: a customer without an active unlock for this CIN does NOT 403; they receive a `200` with the unlock-status JSON above.

**404** Filing not found, or PDF not yet downloaded (`DOC_NOT_AVAILABLE`).

*PDF not yet downloaded into our cache*

```json
{
  "error": {
    "code": "DOC_NOT_AVAILABLE",
    "message": "The PDF for this filing has not been downloaded yet. PDFs are fetched by the company unlock — check progress with GET /v1/companies/{cin}/unlock. POST /v1/companies/{cin}/update refreshes the filing list only and does not fetch PDFs."
  }
}
```

#### List extracted form types

`GET /v1/companies/{cin}/extractions`

Group: Documents and financials. Page: https://api.filesure.in/reference/list-extractions.md

**What it returns**

The MCA form types FileSure has extracted structured data for on this CIN. The array is sorted alphabetically and contains any subset of:

- `AOC-4` — annual financial statements (balance sheet, P&L, cash flow). XBRL extraction from MCA Form AOC-4.
- `CHARGES` — charges (mortgages, hypothecations, secured loans) registered against the company's assets. Multi-level structure: one CIN has many charges; each charge has a lifecycle of CREATION → MODIFICATION* → SATISFACTION events. Addressed by MCA's public `charge_id` string (numeric, e.g. `"10596825"`).
- `MGT-7` — annual return (share capital, directors, KMP, meetings, holding/subsidiary, share-holding pattern). Covers both MGT-7 (large companies) and MGT-7A (small companies / OPC) — the response carries `form_type` to indicate which variant was actually filed.
- `PAS-3` — share allotment events (Return of Allotment). Per-filing equity / preference / debt capital structure + per-allotment details (date, type, mode, security, total amount). Multiple filings per company across its lifetime — addressed by an opaque `filing_id` token (not a year).

Empty array when no extractions exist for the CIN.

**Billing**

Billed per call.

**Sandbox behavior**

Test keys (`fsk_test_*`) work freely on sandbox-whitelisted CINs/LLPINs. Outside the whitelist: `403 SANDBOX_ONLY`.

**Common errors**

- `400 INVALID_CIN` — identifier failed CIN/FCIN/LLPIN format validation

Plus the global auth/wallet/permission errors — see the [error codes table](https://api.filesure.in/reference/start-here/responses-and-errors.md).

**See also**

- [List extracted years](https://api.filesure.in/reference/list-extraction-years.md)
- [Get extracted data](https://api.filesure.in/reference/get-extraction-data.md)

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `cin` | path | yes | string | Company identifier. One of three formats — accepted on `/v1/companies/:cin`: - **CIN** — 21-character Indian Corporate Identification Number (e.g., U72900PB2022PTC055860) - **FCIN** — 6-character Foreign Company Identification Number (e.g., F07030) - **LLPIN** — 8-character LLP Identification Number (e.g., AAA-1234) Pair with the optional `?idType=cin\|fcin\|llpin` query param for stricter validation; auto-detect when omitted. Test keys (`fsk_test_*`) can only call identifiers in the **Sandbox** allowlist — see the Sandbox tag in the sidebar for the full list of 50 sample CINs and 2 LLPINs. |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/companies/U74999HR2015FTC056386/extractions" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** List of available form types

*Listed company — all four form types extracted*

```json
{
  "data": {
    "availableFormTypes": [
      "AOC-4",
      "CHARGES",
      "MGT-7",
      "PAS-3"
    ]
  },
  "meta": {}
}
```

*Established company with debt — financials + annual return + charges*

```json
{
  "data": {
    "availableFormTypes": [
      "AOC-4",
      "CHARGES",
      "MGT-7"
    ]
  },
  "meta": {}
}
```

*Mid-cap — financials + annual return (no debt, no allotments)*

```json
{
  "data": {
    "availableFormTypes": [
      "AOC-4",
      "MGT-7"
    ]
  },
  "meta": {}
}
```

*Older LLP — only charges history extracted*

```json
{
  "data": {
    "availableFormTypes": [
      "CHARGES"
    ]
  },
  "meta": {}
}
```

*Newly-incorporated company — no extractions yet*

```json
{
  "data": {
    "availableFormTypes": []
  },
  "meta": {}
}
```

**400** Identifier failed format validation, or unknown idType value

*Identifier doesn't match CIN/FCIN/LLPIN format*

```json
{
  "error": {
    "code": "INVALID_CIN",
    "message": "The provided identifier failed format validation. Expected CIN, FCIN, or LLPIN."
  }
}
```

*Unknown idType query value*

```json
{
  "error": {
    "code": "INVALID_ID_TYPE",
    "message": "Unknown idType. Valid values: cin, fcin, llpin."
  }
}
```

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

**402** Wallet balance is below the endpoint price

```json
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient wallet balance. Please recharge.",
    "balancePaisa": 0,
    "requiredPaisa": 500
  }
}
```

**403** No pricing assigned, or test key tried to access non-sandbox CIN/DIN

*No pricing record (live key)*

```json
{
  "error": {
    "code": "NO_ACCESS",
    "message": "No access to endpoint 'companies.master'. Contact support to enable access.",
    "endpoint": "companies.master",
    "catalogPricePaisa": 500
  }
}
```

*Test key outside sandbox whitelist*

```json
{
  "error": {
    "code": "SANDBOX_ONLY",
    "message": "A test key only works on the sandbox companies and directors. They are listed in this response and at GET /v1/sandbox. Use one of those, or a live key.",
    "sandboxCompanies": [
      {
        "cin": "U74999HR2015FTC056386",
        "company": "CARS24 SERVICES PRIVATE LIMITED",
        "knownAs": "Cars24"
      },
      {
        "cin": "L93030DL2010PLC198141",
        "company": "ETERNAL LIMITED",
        "knownAs": "Eternal, formerly Zomato"
      }
    ],
    "sandboxDirectors": [
      {
        "din": "11692472",
        "fullName": "NILESH KASHINATH HIWALE"
      }
    ],
    "nextStep": "GET /v1/sandbox"
  }
}
```

#### List extracted years

`GET /v1/companies/{cin}/extractions/{formType}`

Group: Documents and financials. Page: https://api.filesure.in/reference/list-extraction-years.md

**What it returns — depends on `formType`**

The shape of this endpoint's response differs significantly by form type because the per-form lifecycle differs. `formType` is case-insensitive.

- **AOC-4** — returns `{formType, availableYears}` with the calendar end-years of `period_end` (e.g. `"2024-03-31"` → `2024`). Union across `filing_scope` (standalone + consolidated); pick scope on the data endpoint.
- **MGT-7** — returns `{formType, availableYears}` with the calendar year of `fyEnd` (financial year end). MGT-7 + MGT-7A both contribute to the same list (the form-variant distinction lives on the data endpoint's `form_type` field). No `filing_scope` split.
- **PAS-3** — returns `{form_type, latest_snapshot, filings[]}`. Different shape because PAS-3 is event-based (one filing per share allotment, multiple per year). `latest_snapshot` is the consolidated capital structure as-of the most recent allotment date. Each entry in `filings[]` carries a `filing_id` opaque token (use it on the data endpoint), `filing_date`, `as_of_date`, optional `srn`, and `allotment_count`. Sorted by `filing_date` descending.
- **CHARGES** — returns `{form_type, charges[]}`. One entry per `charge_id` (MCA's public numeric charge identifier — e.g. `"10596825"`). Each summary carries `charge_id`, `status` (`ACTIVE` / `SATISFIED` / `OPEN`), `holder_name` + `holder_category` (lender details), `amount_inr` + `amount_crore` (current outstanding), `counts` (creation/modification/satisfaction event counts), `first_event_date`, `latest_event_date`, `latest_event_type`. Sorted by `latest_event_date` descending. Hand the `charge_id` to the data endpoint for the full lifecycle of events.

**Relationship to the master-data endpoint** — `/v1/companies/{cin}` already includes a flat `indexChargesData[]` inline summary (suitable for at-a-glance views in a company profile UI). The dedicated `/extractions/CHARGES` endpoint **augments** that — it surfaces the full lifecycle history (CREATION → MODIFICATION* → SATISFACTION) and per-event details. Use the master-data inline summary for quick views; use these dedicated endpoints for due-diligence-grade lifecycle analysis.

**Billing**

Billed per call.

**Sandbox behavior**

Test keys (`fsk_test_*`) work freely on sandbox-whitelisted CINs/LLPINs. Outside the whitelist: `403 SANDBOX_ONLY`.

**Common errors**

- `400 INVALID_CIN` — identifier failed CIN/FCIN/LLPIN format validation
- `404 FORM_TYPE_NOT_AVAILABLE` — form type unknown to FileSure (supported: `AOC-4`, `CHARGES`, `MGT-7`, `PAS-3`)

Plus the global auth/wallet/permission errors — see the [error codes table](https://api.filesure.in/reference/start-here/responses-and-errors.md).

**See also**

- [List extracted form types](https://api.filesure.in/reference/list-extractions.md)
- [Get extracted data](https://api.filesure.in/reference/get-extraction-data.md)

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `cin` | path | yes | string | Company identifier. One of three formats — accepted on `/v1/companies/:cin`: - **CIN** — 21-character Indian Corporate Identification Number (e.g., U72900PB2022PTC055860) - **FCIN** — 6-character Foreign Company Identification Number (e.g., F07030) - **LLPIN** — 8-character LLP Identification Number (e.g., AAA-1234) Pair with the optional `?idType=cin\|fcin\|llpin` query param for stricter validation; auto-detect when omitted. Test keys (`fsk_test_*`) can only call identifiers in the **Sandbox** allowlist — see the Sandbox tag in the sidebar for the full list of 50 sample CINs and 2 LLPINs. |
| `formType` | path | yes | string | MCA form whose extraction to access. Today only `AOC-4` (annual financials) is extracted; future forms will be added as additional extractors come online. Case-insensitive — `aoc-4` and `AOC-4` both match. |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/companies/U74999HR2015FTC056386/extractions/AOC-4" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** Available years for AOC-4 / MGT-7, OR latest snapshot + filings list for PAS-3, OR per-charge summaries for CHARGES. Shape depends on `formType` — see the per-form details in the endpoint description.

*AOC-4 — years available (descending)*

```json
{
  "data": {
    "formType": "AOC-4",
    "availableYears": [
      2025,
      2024,
      2022,
      2021,
      2020,
      2019,
      2018,
      2017,
      2016
    ]
  },
  "meta": {}
}
```

*MGT-7 — years (one annual return per FY)*

```json
{
  "data": {
    "formType": "MGT-7",
    "availableYears": [
      2025,
      2024,
      2023,
      2022,
      2021,
      2020,
      2019
    ]
  },
  "meta": {}
}
```

*CHARGES — per-charge summaries (different shape than AOC-4/MGT-7)* Real charges list for a CIN with multi-event lifecycle. Sorted by latest_event_date desc. Each summary carries enough to identify the charge + its current state at a glance — drill into the detail endpoint via `charge_id` for the full event timeline.

```json
{
  "data": {
    "form_type": "CHARGES",
    "charges": [
      {
        "charge_id": "10596825",
        "status": "ACTIVE",
        "holder_name": "HDFC BANK LIMITED",
        "holder_category": "Private Sector Bank",
        "amount_inr": 1249843306,
        "amount_crore": 124.9843306,
        "counts": {
          "creation": 1,
          "modification": 14,
          "satisfaction": 0
        },
        "first_event_date": "2015-08-29T00:00:00.000Z",
        "latest_event_date": "2024-05-04T00:00:00.000Z",
        "latest_event_type": "MODIFICATION"
      },
      {
        "charge_id": "100459847",
        "status": "ACTIVE",
        "holder_name": "HDFC BANK LIMITED",
        "holder_category": "Private Sector Bank",
        "amount_inr": 2992000,
        "amount_crore": 0.2992,
        "counts": {
          "creation": 1,
          "modification": 0,
          "satisfaction": 0
        },
        "first_event_date": "2021-05-04T00:00:00.000Z",
        "latest_event_date": "2021-05-04T00:00:00.000Z",
        "latest_event_type": "CREATION"
      }
    ]
  },
  "meta": {
    "createdAt": "2026-04-15T10:22:00.000Z",
    "updatedAt": "2026-05-08T03:14:00.000Z"
  }
}
```

*PAS-3 — latest snapshot + filings list (different shape than AOC-4/MGT-7)* Real PAS-3 list for a high-cardinality listed company. Capital amounts surface as strings (BSON Decimal128) to preserve precision; share counts as JS numbers when they fit in `Number.MAX_SAFE_INTEGER` (else strings).

```json
{
  "data": {
    "form_type": "PAS-3",
    "latest_snapshot": {
      "filing_id": "flg_xKpQyNwz3FdJaT_l5sA9bKp4XmHfVc_pQk1nR5tWzE2YuJrCqL3mNbDgHvSf",
      "as_of_date": "2025-04-30T00:00:00.000Z",
      "filing_date": "2025-05-29T00:00:00.000Z",
      "srn": "AB4296232",
      "equity": {
        "authorised": {
          "shares": 49000000000,
          "nominal": "10",
          "total": "490000000000.00"
        },
        "issued": {
          "shares": 13532472634,
          "nominal": "10",
          "total": "135324726340.00"
        },
        "subscribed": {
          "shares": 13532472634,
          "nominal": "10",
          "total": "135324726340.00"
        },
        "paid_up": {
          "shares": 13532472634,
          "nominal": "10",
          "total": "135324726340.00"
        }
      }
    },
    "filings": [
      {
        "filing_id": "flg_xKpQyNwz3FdJaT_l5sA9bKp4XmHfVc_pQk1nR5tWzE2YuJrCqL3mNbDgHvSf",
        "filing_date": "2025-05-29T00:00:00.000Z",
        "as_of_date": "2025-04-30T00:00:00.000Z",
        "srn": "AB4296232",
        "allotment_count": 1
      },
      {
        "filing_id": "flg_2bMc7VxNqRfDjY_t8wL5pXk3FzEhSa_nWy6oQ4mUrJiKvBtCgL9pHbNzGfM7",
        "filing_date": "2024-11-22T00:00:00.000Z",
        "as_of_date": "2024-10-31T00:00:00.000Z",
        "srn": "AB1812685",
        "allotment_count": 1
      }
    ]
  },
  "meta": {
    "createdAt": "2024-10-22T03:14:00.000Z",
    "updatedAt": "2025-05-29T07:55:46.687Z"
  }
}
```

**400** Identifier failed format validation, or unknown idType value

*Identifier doesn't match CIN/FCIN/LLPIN format*

```json
{
  "error": {
    "code": "INVALID_CIN",
    "message": "The provided identifier failed format validation. Expected CIN, FCIN, or LLPIN."
  }
}
```

*Unknown idType query value*

```json
{
  "error": {
    "code": "INVALID_ID_TYPE",
    "message": "Unknown idType. Valid values: cin, fcin, llpin."
  }
}
```

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

**402** Wallet balance is below the endpoint price

```json
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient wallet balance. Please recharge.",
    "balancePaisa": 0,
    "requiredPaisa": 500
  }
}
```

**403** No pricing assigned, or test key tried to access non-sandbox CIN/DIN

*No pricing record (live key)*

```json
{
  "error": {
    "code": "NO_ACCESS",
    "message": "No access to endpoint 'companies.master'. Contact support to enable access.",
    "endpoint": "companies.master",
    "catalogPricePaisa": 500
  }
}
```

*Test key outside sandbox whitelist*

```json
{
  "error": {
    "code": "SANDBOX_ONLY",
    "message": "A test key only works on the sandbox companies and directors. They are listed in this response and at GET /v1/sandbox. Use one of those, or a live key.",
    "sandboxCompanies": [
      {
        "cin": "U74999HR2015FTC056386",
        "company": "CARS24 SERVICES PRIVATE LIMITED",
        "knownAs": "Cars24"
      },
      {
        "cin": "L93030DL2010PLC198141",
        "company": "ETERNAL LIMITED",
        "knownAs": "Eternal, formerly Zomato"
      }
    ],
    "sandboxDirectors": [
      {
        "din": "11692472",
        "fullName": "NILESH KASHINATH HIWALE"
      }
    ],
    "nextStep": "GET /v1/sandbox"
  }
}
```

**404** Form type is not extracted by FileSure

*Unknown form type*

```json
{
  "error": {
    "code": "FORM_TYPE_NOT_AVAILABLE",
    "message": "Form type \"XYZ-99\" is not extracted. Supported: AOC-4, CHARGES, MGT-7, PAS-3."
  }
}
```

#### Get extracted data

`GET /v1/companies/{cin}/extractions/{formType}/{year}`

Group: Documents and financials. Page: https://api.filesure.in/reference/get-extraction-data.md

**What it returns — depends on `formType`**

Structured data extracted from the requested form filing. The path parameter formerly named `{year}` is reused per-form:

- **AOC-4** — `{year}` is the calendar end-year (e.g. `2024`). Returns three arrays of `{qname, value, unit}` triplets covering balance sheet, profit & loss, and cash flow (XBRL output). Standalone vs consolidated are stored as separate extractions; pick via `?scope=` (default `standalone`). If only one scope exists for a year, requesting the other returns `404` with a hint.
- **MGT-7** — `{year}` is the calendar year of `fyEnd` (e.g. `2024` matches a financial year ending Mar 2024). Returns annual return contents: registration details (`form_type` indicating MGT-7 vs MGT-7A, `fy_start`, `fy_end`, `agm_date`, `srn`, `filing_date`), principal business activities, holding/subsidiary companies, share capital + share-holding pattern, turnover + net worth, directors + KMP, meetings + attendance, remuneration. `?scope=` is ignored on MGT-7.
- **PAS-3** — `{year}` slot reused for an opaque **`filing_id`** token (`flg_...`). Obtain a `filing_id` from the list endpoint above, then drop it into this URL slot. Returns full filing payload: per-event `capital_structure` (equity + preference + debt) + chronological `allotments[]` (each with date, type, mode, securities, amounts). The same token format is also used by the [filings download endpoint](https://api.filesure.in/reference/download-filing.md) — tokens are reversible only by the server (AES-encrypted `(cin, documentCode)`), so a token from one CIN's URL won't work on another CIN's URL (returns 404).
- **CHARGES** — `{year}` slot reused for the **`charge_id`** (MCA's public numeric charge identifier, e.g. `"10596825"`). Obtain a `charge_id` from the list endpoint above. Returns full charge lifecycle: `current` consolidated state (omitted on `SATISFIED` charges where there's nothing currently active) + `counts` + `events[]` — chronologically ascending CREATION → MODIFICATION* → SATISFACTION events. Each event carries `event_type`, `event_date`, `filing_date`, `srn`, plus the per-event detail subdocs (`charge` with amount + roi + repay terms, `holder` with bank name + category + address, `security`, `asset_particulars`, `desc_of_modification` for MODIFICATION events, `satisfaction` for SATISFACTION events). Older events may have only event-type + dates (variable richness — surface populated fields only, no nulls).

All fields are surfaced verbatim from MCA's filed form — no UI flattening, no derived totals. Customers compose their own views from the raw data.

**Billing**

Unlock-gated. Needs an active company unlock for this CIN, the same unlock that gates filing downloads (one fee covers every extraction of every form type), plus the per-call fee. Without an active unlock this endpoint returns the unlock-status JSON instead of the data (no charge). What an unlock covers: [How FileSure data works](https://api.filesure.in/reference/start-here/how-filesure-data-works.md).

**Sandbox behavior**

Test keys (`fsk_test_*`) on a sandbox-whitelisted CIN return a synthetic unlock state and the real cached extraction; no wallet deduction. Outside the sandbox: `403 SANDBOX_ONLY`.

**Common errors**

- `400 INVALID_CIN` — CIN/FCIN/LLPIN format validation failed
- `400 INVALID_YEAR` — AOC-4/MGT-7: year out of range (must be 1900..currentYear+1)
- `400 INVALID_FILING_ID` — PAS-3: path slot is not a valid `flg_*` token (malformed, or AES-tampered)
- `400 INVALID_CHARGE_ID` — CHARGES: path slot is not a numeric string
- `400 INVALID_QUERY` — `?scope=` set to a value outside the enum (AOC-4 only — ignored on MGT-7/PAS-3/CHARGES)
- `404 EXTRACTION_NOT_AVAILABLE` — AOC-4/MGT-7: no extraction for this `(form, year)`. AOC-4 hint may point to the other `?scope=`
- `404 FILING_NOT_FOUND` — PAS-3: token decodes to a `(cin, documentCode)` that doesn't have a matching event in `pas3_events`, OR the decoded `cin` doesn't match the URL `cin` (cross-CIN paste defense)
- `404 CHARGE_NOT_FOUND` — CHARGES: no charge with the given `charge_id` exists for this CIN
- `404 FORM_TYPE_NOT_AVAILABLE` — form type unknown (supported: `AOC-4`, `CHARGES`, `MGT-7`, `PAS-3`)

Plus the global auth/wallet/permission errors — see the [error codes table](https://api.filesure.in/reference/start-here/responses-and-errors.md).

**See also**

- [List extracted form types](https://api.filesure.in/reference/list-extractions.md)
- [List extracted years](https://api.filesure.in/reference/list-extraction-years.md)
- [Unlock a company](https://api.filesure.in/reference/unlock-company.md)

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `cin` | path | yes | string | Company identifier. One of three formats — accepted on `/v1/companies/:cin`: - **CIN** — 21-character Indian Corporate Identification Number (e.g., U72900PB2022PTC055860) - **FCIN** — 6-character Foreign Company Identification Number (e.g., F07030) - **LLPIN** — 8-character LLP Identification Number (e.g., AAA-1234) Pair with the optional `?idType=cin\|fcin\|llpin` query param for stricter validation; auto-detect when omitted. Test keys (`fsk_test_*`) can only call identifiers in the **Sandbox** allowlist — see the Sandbox tag in the sidebar for the full list of 50 sample CINs and 2 LLPINs. |
| `formType` | path | yes | string | MCA form whose extraction to access. Today only `AOC-4` (annual financials) is extracted; future forms will be added as additional extractors come online. Case-insensitive — `aoc-4` and `AOC-4` both match. |
| `year` | path | yes | string | Per-form axis (path-slot name reused historically): - **AOC-4 / MGT-7**: 4-digit calendar end-year (e.g. `2024`). Must be in `[1900, currentYear+1]`. - **PAS-3**: opaque `flg_*` filing_id token from the list endpoint's `filings[].filing_id`. - **CHARGES**: numeric `charge_id` (e.g. `"10596825"`) from the list endpoint's `charges[].charge_id`. |
| `scope` | query | no | string (`standalone`, `consolidated`) | Which filing scope to return. Defaults to standalone. (default "standalone") |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/companies/U74999HR2015FTC056386/extractions/AOC-4/2024" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** Extraction data (shape depends on `formType`), OR unlock-status payload when not unlocked.

*AOC-4 standalone for 2024 (truncated, CARS24)* Real AOC-4 extractions have 80–100 rows per array; example shows 1 representative row each.

```json
{
  "data": {
    "cin": "U74999HR2015FTC056386",
    "filing_scope": "standalone",
    "period_end": "2024-03-31",
    "period_start": "2023-04-01",
    "taxonomy_id": "in-ca:Schedule3IndAS",
    "balance_sheet": [
      {
        "qname": "in-ca:Equity",
        "value": 12450000000,
        "unit": "INR"
      }
    ],
    "profit_and_loss": [
      {
        "qname": "in-ca:RevenueFromOperations",
        "value": 89400000000,
        "unit": "INR"
      }
    ],
    "cash_flow": [
      {
        "qname": "in-ca:CashFlowsFromUsedInOperatingActivities",
        "value": -3210000000,
        "unit": "INR"
      }
    ],
    "metadata": {
      "source": {
        "dateOfFiling": "30/09/2024",
        "paymentDate": "28/09/2024",
        "year": 2024
      }
    }
  },
  "meta": {
    "createdAt": "2024-09-30T14:22:18.000Z",
    "updatedAt": "2024-10-12T08:05:42.000Z"
  }
}
```

*MGT-7 annual return for 2025 (truncated, listed company L15400TG2009PLC062658)* Listed company MGT-7 with full sections. Real responses have all populated MCA sections; example trims nested arrays to one representative row. `form_type` reflects which actual filing variant was used (`MGT-7` for standard, `MGT-7A` for small companies / OPC).

```json
{
  "data": {
    "cin": "L15400TG2009PLC062658",
    "form_type": "MGT-7",
    "srn": "AC0745199",
    "fy_start": "2024-04-01T00:00:00.000Z",
    "fy_end": "2025-03-31T00:00:00.000Z",
    "agm_date": "2025-09-24T00:00:00.000Z",
    "filing_date": "2025-12-28T00:00:00.000Z",
    "is_opc": false,
    "is_share_listed": true,
    "number_stock_exchange": 1,
    "stock_exchanges": [
      "BSE"
    ],
    "num_business_actv": 3,
    "business_activities": [
      {
        "main_group_code": "N",
        "main_group_desc": "Administrative and support service activities",
        "activity_code": "80",
        "activity_desc": "Security and investigation activities",
        "turnover_pct": 29.89
      }
    ],
    "num_rtas": 1,
    "rtas": [
      {
        "cin_other_reg_no": "U72400TG2017PTC117649",
        "name_of_rta": "KFin Technologies Limited",
        "address1": "Selenium Tower-B, Plot 31 & 32"
      }
    ],
    "num_holding_subs": 2,
    "holding_subs": [],
    "share_capital": {
      "equity": {
        "num_classes": 1,
        "totals": {
          "shares": {
            "authorised": 23000000,
            "issued": 20288122,
            "subscribed": 20288122,
            "paid_up": 20288122
          },
          "amount": {
            "authorised": 115000000,
            "issued": 101440610,
            "subscribed": 101440610,
            "paid_up": 101440610
          }
        }
      },
      "preference": {
        "num_classes": 0,
        "totals": {
          "shares": {
            "authorised": 0,
            "issued": 0,
            "subscribed": 0,
            "paid_up": 0
          },
          "amount": {
            "authorised": 0,
            "issued": 0,
            "subscribed": 0,
            "paid_up": 0
          }
        }
      },
      "unclassified_total": 0
    },
    "share_holding_pattern": {
      "promoter": {
        "equity_pct": 50.78,
        "preference_pct": 0
      },
      "public": {
        "equity_pct": 49.22,
        "preference_pct": 0
      }
    },
    "turnover": 6887017470,
    "net_worth": 888754630,
    "meetings": {
      "members_total": 1,
      "board_total": 4,
      "committee_total": 12,
      "directors_attendance": []
    },
    "kmp": [
      {
        "din": "00037022",
        "name": "Prem Kishan Dass Gupta",
        "designation": "MANAGING DIRECTOR"
      }
    ],
    "remuneration": {
      "directors": [],
      "total": 0
    }
  },
  "meta": {
    "createdAt": "2026-04-20T08:34:29.719Z",
    "updatedAt": "2026-04-20T08:34:29.719Z"
  }
}
```

*PAS-3 — full filing detail for a single share allotment (listed company, L17110MH1973PLC019786)* The `:filing_id` path slot carries a `flg_*` token (from the list endpoint). Returns the per-event `capital_structure` (equity + preference + debt) + chronological `allotments[]` array. Decimal128 values surface as strings to preserve precision.

```json
{
  "data": {
    "cin": "L17110MH1973PLC019786",
    "form_type": "PAS-3",
    "filing_id": "flg_xKpQyNwz3FdJaT_l5sA9bKp4XmHfVc_pQk1nR5tWzE2YuJrCqL3mNbDgHvSf",
    "filing_date": "2025-05-29T00:00:00.000Z",
    "srn": "AB4296232",
    "capital_structure": {
      "equity": {
        "authorised": {
          "shares": 49000000000,
          "nominal": "10",
          "total": "490000000000.00"
        },
        "issued": {
          "shares": 13532472634,
          "nominal": "10",
          "total": "135324726340.00"
        },
        "subscribed": {
          "shares": 13532472634,
          "nominal": "10",
          "total": "135324726340.00"
        },
        "paid_up": {
          "shares": 13532472634,
          "nominal": "10",
          "total": "135324726340.00"
        }
      },
      "preference": {
        "authorised": {
          "shares": 1000000000,
          "nominal": "10",
          "total": "10000000000.00"
        },
        "issued": {
          "shares": 0,
          "nominal": "0",
          "total": "0.00"
        },
        "subscribed": {
          "shares": 0,
          "nominal": "0",
          "total": "0.00"
        },
        "paid_up": {
          "shares": 0,
          "nominal": "0",
          "total": "0.00"
        }
      },
      "debt": {
        "debentures": "283888000000",
        "secured_loans": "73708977566.46",
        "others": "1610154091933.08"
      }
    },
    "allotments": [
      {
        "allotment_date": "2025-04-30T00:00:00.000Z",
        "security_type": "Equity",
        "allotment_type": "Employee stock option Plan (ESOP)",
        "details": "PARI-PASSU WITH EXISTING FULLY PAID-UP EQ SHARES",
        "terms_in_attachment": false,
        "mode": "Cash",
        "num_securities_allotted": 99736,
        "nominal_per_security": "10",
        "premium_per_security": "0",
        "discount_per_security": "0",
        "total_amount": "997360",
        "non_cash": null
      }
    ]
  },
  "meta": {
    "createdAt": "2025-05-29T07:55:46.687Z",
    "updatedAt": "2025-05-29T07:55:46.687Z"
  }
}
```

*CHARGES — full lifecycle for one charge (HDFC working-capital, U27100PB1996PLC017827)* Real charge with 15 events (1 creation + 14 modifications, no satisfaction — still ACTIVE). `current` block carries the consolidated state-as-of-now; `events[]` is chronologically ascending. Older events have less rich per-event detail (variable richness — surface populated fields only, no nulls).

```json
{
  "data": {
    "cin": "U27100PB1996PLC017827",
    "form_type": "CHARGES",
    "charge_id": "10596825",
    "status": "ACTIVE",
    "counts": {
      "creation": 1,
      "modification": 14,
      "satisfaction": 0
    },
    "current": {
      "amount_inr": 1249843306,
      "amount_crore": 124.9843306,
      "roi_pct": "9.50%",
      "holder_name": "HDFC BANK LIMITED",
      "holder_category": "Private Sector Bank",
      "num_holders": 1,
      "flags": {
        "is_joint": false,
        "is_consortium": false,
        "is_pari_passu": false
      },
      "property_type_raw": [
        "Movable property - Inventory",
        "Movable property - Motor Vehicle (Hypothecation)",
        "Movable property - Others",
        "Book debts"
      ],
      "property_types": [
        "MOVABLE_INVENTORY",
        "VEHICLES",
        "MOVABLE_PROPERTY",
        "BOOK_DEBTS"
      ],
      "instrument_desc": "Supplementary Letter of Hypothecation."
    },
    "events": [
      {
        "event_type": "CREATION",
        "event_date": "2015-08-29T00:00:00.000Z",
        "filing_date": "2015-09-15T00:00:00.000Z",
        "reg_date": "2015-09-15T00:00:00.000Z",
        "srn": "C67177063",
        "charge": {
          "amount_inr": 365000000,
          "amount_crore": 36.5,
          "amount_words": "Rupees Thirty Six Crore Fifty Lacs only",
          "roi_pct": "Interest at the rate as stipulated in the Bank's Sanction Letter.",
          "nature_facility": "MFA",
          "terms_of_repay": "MFA repayable on demand and/or as stipulated in the Bank's Sanction Letter."
        },
        "holder": {
          "is_joint": false,
          "is_consortium": false,
          "is_pari_passu": false,
          "num_holders": 1,
          "category": "PVTB",
          "name_of_chg_holder": "HDFC BANK LIMITED",
          "name": "HDFC BANK LIMITED",
          "add_line1": "HDFC BANK HOUSE, SENAPATI BAPAT MARG",
          "city": "MUMBAI",
          "state": "MH",
          "pin_code": "400013",
          "country": "IN"
        }
      },
      {
        "event_type": "MODIFICATION",
        "event_date": "2020-06-04T00:00:00.000Z",
        "filing_date": "2020-07-03T00:00:00.000Z",
        "srn": "R44284271",
        "desc_of_modification": "The charge shall now stand increased from Rs.3050 Lakhs to Rs.3650 Lakhs in favour of the Bank against the security of Stocks & Book Debts, Plant & Machinery and vehicles and immovable properties...",
        "charge": {
          "amount_inr": 365000000,
          "amount_crore": 36.5
        },
        "holder": {
          "num_holders": 1,
          "category": "PVTB",
          "name_of_chg_holder": "HDFC BANK LIMITED"
        }
      }
    ]
  },
  "meta": {
    "createdAt": "2026-04-15T10:22:00.000Z",
    "updatedAt": "2024-05-08T03:14:00.000Z"
  }
}
```

*Customer hasn't unlocked this CIN yet*

```json
{
  "data": {
    "unlocked": false,
    "unlockPrice": 33000
  },
  "meta": {}
}
```

**400** Invalid CIN, year out of range, or unknown scope value

*AOC-4 / MGT-7 — year out of range*

```json
{
  "error": {
    "code": "INVALID_YEAR",
    "message": "`year` must be between 1900 and the current calendar year + 1."
  }
}
```

*PAS-3 — path slot is not a valid flg_* token*

```json
{
  "error": {
    "code": "INVALID_FILING_ID",
    "message": "`filing_id` is not a valid identifier."
  }
}
```

*CHARGES — path slot is not numeric*

```json
{
  "error": {
    "code": "INVALID_CHARGE_ID",
    "message": "`charge_id` path parameter must be a numeric string."
  }
}
```

**

```json
{
  "error": {
    "code": "INVALID_QUERY",
    "message": "`scope` must be one of: standalone, consolidated."
  }
}
```

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

**403** `SANDBOX_ONLY` — test key (`fsk_test_*`) used outside the sandbox-whitelisted CIN list. `unlockCheck()` doesn't 403 live keys for missing pricing — when no unlock and no pricing record exist, it returns the 200 not-unlocked envelope with `unlockPrice: null`.

```json
{
  "error": {
    "code": "SANDBOX_ONLY",
    "message": "A test key only works on the sandbox companies and directors. They are listed in this response and at GET /v1/sandbox. Use one of those, or a live key.",
    "sandboxCompanies": [
      {
        "cin": "U74999HR2015FTC056386",
        "company": "CARS24 SERVICES PRIVATE LIMITED",
        "knownAs": "Cars24"
      },
      {
        "cin": "L93030DL2010PLC198141",
        "company": "ETERNAL LIMITED",
        "knownAs": "Eternal, formerly Zomato"
      }
    ],
    "sandboxDirectors": [
      {
        "din": "11692472",
        "fullName": "NILESH KASHINATH HIWALE"
      }
    ],
    "nextStep": "GET /v1/sandbox"
  }
}
```

**404** No extraction available for the requested form/year/scope

*AOC-4 / MGT-7 — year has no extraction*

```json
{
  "error": {
    "code": "EXTRACTION_NOT_AVAILABLE",
    "message": "No AOC-4 extraction available for 1995."
  }
}
```

*AOC-4 — other scope is available*

```json
{
  "error": {
    "code": "EXTRACTION_NOT_AVAILABLE",
    "message": "No AOC-4 consolidated extraction for 2024. The standalone extraction is available — try ?scope=standalone."
  }
}
```

*PAS-3 — token decodes successfully but no matching event for this CIN* Returned when the `flg_*` token decodes (valid AES) but either (a) the decoded documentCode doesn't match a PAS-3 event for this CIN, or (b) the decoded `cin` inside the token differs from the URL CIN (cross-CIN paste defense).

```json
{
  "error": {
    "code": "FILING_NOT_FOUND",
    "message": "No PAS-3 filing matches filing_id \"flg_xKpQy...\" for this company."
  }
}
```

*CHARGES — no charge with that charge_id exists for this CIN*

```json
{
  "error": {
    "code": "CHARGE_NOT_FOUND",
    "message": "No charge with charge_id \"9999999999\" exists for this company."
  }
}
```

**

```json
{
  "error": {
    "code": "FORM_TYPE_NOT_AVAILABLE",
    "message": "Form type \"XYZ-99\" is not extracted. Supported: AOC-4, CHARGES, MGT-7, PAS-3."
  }
}
```

### Keep a company current

How current is our copy of a company, and what to do about it. The freshness check is free; a refresh (₹1) re-reads the record and the filing list from MCA; a document fetch (₹150) downloads the listed filings still missing a PDF.

#### How current is our copy of this company?

`GET /v1/companies/{cin}/freshness`

Group: Keep a company current. Page: https://api.filesure.in/reference/get-company-freshness.md

Dates and counts only — no company data — so you can decide whether to pay for a refresh
before you do. **Free.** Covered by the per-key rate limit like the account calls.

**The flow this call starts**

1. `GET /v1/companies/{cin}/freshness` — free. Is the record stale? Are PDFs missing?
2. `POST /v1/companies/{cin}/update` — ₹1. Refreshes the record and the filing list from MCA. No PDFs.
3. `POST /v1/companies/{cin}/documents/fetch` — ₹150. Downloads the PDFs that are still missing (needs your unlock).

**What the fields mean**

| Field | Meaning |
|---|---|
| `data.updatedAt` | When the company's master data, directors, common data and charges were last written. They are refreshed together, so one date is enough. |
| `filings.total` / `downloaded` / `missing` | Our filing index for the company: rows, rows with a PDF on file, rows without. `missing > 0` is what a document job would fetch. |
| `filings.listRefreshedAt` | When the filing list was last re-read from MCA (a data refresh or a filing-list refresh). |
| `refresh` | The newest data refresh for this company, whoever asked for it: `status`, `lastCompletedAt` and `freshUntil` — until then a `POST /update` joins the finished refresh (`alreadyFresh: true`) instead of fetching again. |
| `documentJob` | The newest document download job for this company: `status` (`pending` → `in_progress` → `success`) and its counters. `null` if none has run. |
| `unlock` | Whether **you** hold an active unlock for this company, and when it expires. |

**Sandbox behavior**

`fsk_test_*` keys on a whitelisted CIN return a synthetic, settled shape with `sandbox: true`. Outside the whitelist: `403 SANDBOX_ONLY`.

**Common errors**

- `400 INVALID_CIN` — format validation failed
- `404 COMPANY_NOT_FOUND` — we do not hold this company

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `cin` | path | yes | string | 21-character Corporate Identification Number (CIN). |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/companies/U74999HR2015FTC056386/freshness" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** Freshness of our data for this company

```json
{
  "data": {
    "cin": "U62013KA2024PTC188236",
    "data": {
      "updatedAt": "2026-09-13T22:10:04.000Z"
    },
    "filings": {
      "total": 30,
      "downloaded": 21,
      "missing": 9,
      "listRefreshedAt": "2026-09-13T22:10:19.000Z"
    },
    "refresh": {
      "jobId": "6aa7f0c1b22e2991f01371aa",
      "status": "completed",
      "requestedAt": "2026-09-13T22:09:52.000Z",
      "lastCompletedAt": "2026-09-13T22:10:19.000Z",
      "freshUntil": "2026-09-14T22:10:19.000Z"
    },
    "documentJob": {
      "status": "success",
      "totalDocuments": 21,
      "downloadedDocuments": 21,
      "pendingDocuments": 0,
      "createdAt": "2026-08-03T06:49:12.000Z",
      "updatedAt": "2026-08-03T07:02:40.000Z"
    },
    "unlock": {
      "active": true,
      "unlockedAt": "2026-08-16T09:12:40.000Z",
      "expiresAt": "2027-08-16T09:12:40.000Z"
    }
  },
  "meta": {}
}
```

**400** Identifier failed format validation, or unknown idType value

*Identifier doesn't match CIN/FCIN/LLPIN format*

```json
{
  "error": {
    "code": "INVALID_CIN",
    "message": "The provided identifier failed format validation. Expected CIN, FCIN, or LLPIN."
  }
}
```

*Unknown idType query value*

```json
{
  "error": {
    "code": "INVALID_ID_TYPE",
    "message": "Unknown idType. Valid values: cin, fcin, llpin."
  }
}
```

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

**403** Test key on a non-sandbox CIN.

**404** We do not hold this company.

#### Refresh a company from MCA

`POST /v1/companies/{cin}/update`

Group: Keep a company current. Page: https://api.filesure.in/reference/update-company.md

Fetches this company again from MCA, now, and updates what we hold: its master data, its
director list, its common data and its filing list. Returns `202 Accepted` with a job id.
**₹1** — a nominal fee, because the refresh also improves our own data.

**This refreshes data, not documents.** It fetches no PDFs. Unlock buys you the company's
*documents* — PDFs and extracted financials — for a year; once unlocked, new filings the
refresh finds are downloaded by `POST /v1/companies/{cin}/documents/fetch` (₹150). Update
refreshes the *record*: name, status, registered address, capital, directors, charges, and
the list of filings. If you unlocked a company last year and want to know whether anything
has changed since, this is the call — and it is free to find out first with
`GET /v1/companies/{cin}/freshness`.

Where this sits in the flow, and what the other two calls do: [How FileSure data works](https://api.filesure.in/reference/start-here/how-filesure-data-works.md).

**What to do next is in the response.** `documents.newFilings` is how many filings the
refresh added to our list; once the job is `completed`, `documents.missing` is how many
listed filings have no PDF on file and `documents.nextStep` names the document job when that
is above zero.

**It is asynchronous.** A live MCA fetch takes seconds to minutes and can fail on captcha or
upstream quota, so the response comes back immediately with a job id. Poll
`GET /v1/companies/{cin}/update/status` for progress.

**Stages are reported separately**, because a partial refresh is the normal case rather than
the exception:

| Stage | What it refreshes |
|---|---|
| `masterData` | Company name, status, dates, address, capital |
| `directors` | The board as MCA currently lists it |
| `commonData` | PAN and associated identifiers |
| `documents` | The filing index on our side |

A stage reads `completed`, `failed` or `skipped`. `skipped` means we chose not to run it —
the director list is read from the master-data response, so it is skipped when that stage
fails. It does not mean an error.

**One refresh per company per 24 hours, shared.** If someone else already asked for this
company inside that window you join their job rather than starting a second scrape, and the
response carries `joinedExisting: true`. Where their refresh has already finished you also
get `alreadyFresh: true` — the data was current before you asked, and no new fetch was run.
`freshUntil` says when the window ends (`cooldownUntil` is the same value, kept for older
integrations). Every call is charged, including one that joins.

**Rate limit:** 10 companies per minute, separate from the general per-key limit. Each
refresh is a live MCA round trip, not a cached read.

**Billing**

Charges your `companies.update` rate (see the [rate card](https://api.filesure.in/pricing.html)) on success, including when you join a
running or freshly-completed refresh. If the refresh cannot be queued you get `503` and are
**not** charged.

**Sandbox behavior**

`fsk_test_*` keys on a whitelisted CIN return a synthetic completed job. No MCA fetch, no
charge, no job record.

**Common errors**

- `400 INVALID_CIN` — format validation failed
- `402 INSUFFICIENT_BALANCE` — wallet below the update fee; nothing queued
- `404 COMPANY_NOT_FOUND` — we do not hold this company; no charge
- `429 RATE_LIMITED` — past 10 refreshes/minute; no charge
- `409 REFRESH_IN_PROGRESS` — a filing-list-only refresh (`POST /v1/companies/{cin}/filings/refresh`) is running for this company; retry after `Retry-After` seconds to start the full refresh. No charge
- `503 UPDATE_QUEUE_UNAVAILABLE` — could not queue; no charge, safe to retry

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `cin` | path | yes | string |  |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/companies/U74999HR2015FTC056386/update" \
  -X POST \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**202** Refresh queued, or joined to one already running

```json
{
  "data": {
    "cin": "U74999HR2015FTC056386",
    "jobId": "6a7c6b00b22e2991f0137105",
    "status": "pending",
    "requestedAt": "2026-08-12T12:45:52.000Z",
    "lastCompletedAt": null,
    "freshUntil": null,
    "cooldownUntil": null,
    "stages": {
      "masterData": {
        "status": "pending"
      },
      "directors": {
        "status": "pending"
      },
      "commonData": {
        "status": "pending"
      },
      "documents": {
        "status": "pending"
      }
    }
  },
  "meta": {
    "priceChargedPaisa": 100,
    "walletBalanceAfterPaisa": 44190
  }
}
```

**402** Insufficient wallet balance

**404** Company not found

**429** Refresh rate limit exceeded

**503** Could not queue the refresh — not charged

#### Progress of a company refresh

`GET /v1/companies/{cin}/update/status`

Group: Keep a company current. Page: https://api.filesure.in/reference/get-company-update-status.md

Per-stage progress for the most recent refresh of this company. Free.

The job is per *company*, not per customer — if you joined someone else's refresh, this
shows you its progress.

`status` is `pending`, `in_progress`, `completed` or `failed`. It reads `failed` when any
stage failed, so check the individual stages to see what did land: three of four refreshed
is a normal outcome and better than none.

`freshUntil` (and its older alias `cooldownUntil`) is set only on a successful refresh —
24 hours after it completed. A failed one never blocks a retry.

`documents` says what the refresh found: `newFilings` added to our list, and once the job
is `completed`, `missing` (listed filings with no PDF on file) and `nextStep`, which names
`POST /v1/companies/{cin}/documents/fetch` when there is something to download.

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `cin` | path | yes | string |  |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/companies/U74999HR2015FTC056386/update/status" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** Current refresh state

```json
{
  "data": {
    "cin": "U74999HR2015FTC056386",
    "jobId": "6a7c6b00b22e2991f0137105",
    "status": "completed",
    "requestedAt": "2026-08-12T12:45:52.000Z",
    "lastCompletedAt": "2026-08-12T12:46:07.000Z",
    "freshUntil": "2026-08-13T12:46:07.000Z",
    "cooldownUntil": "2026-08-13T12:46:07.000Z",
    "stages": {
      "masterData": {
        "status": "completed"
      },
      "directors": {
        "status": "completed"
      },
      "commonData": {
        "status": "completed"
      },
      "documents": {
        "status": "completed"
      }
    },
    "documents": {
      "newFilings": 9,
      "missing": 9,
      "nextStep": "POST /v1/companies/{cin}/documents/fetch"
    }
  }
}
```

#### Fetch new documents for an unlocked company

`POST /v1/companies/{cin}/documents/fetch`

Group: Keep a company current. Page: https://api.filesure.in/reference/fetch-company-documents.md

Queues a download of the filings whose PDFs we do not hold yet, for a company you have
already unlocked. Returns `202 Accepted`; watch progress at
[GET /v1/companies/{cin}/unlock](https://api.filesure.in/reference/get-company-unlock.md).

**When to use it.** The ₹330 unlock includes the first download. Months later the company
has filed more, and a data refresh (`POST /v1/companies/{cin}/update`) has listed the new
filings — but a refresh never fetches PDFs. This call does: it starts a new download job
for everything in the filing list that is still missing a PDF.

**The flow**

1. `POST /v1/companies/{cin}/unlock` — once, opens a 1-year window and runs the first download.
2. `POST /v1/companies/{cin}/update` — ₹1, pulls the current filing list from MCA.
3. `POST /v1/companies/{cin}/documents/fetch` — ₹150, downloads the PDFs that appeared.

**Rules**

- **Needs your active unlock** for this company. Without one: `403 UNLOCK_REQUIRED` with
  `nextStep` pointing at the unlock, and **no charge**.
- **Nothing missing, nothing charged.** If every filing we list already has its PDF (or we
  hold no filing list yet), you get `409 NOTHING_TO_FETCH` with the counts and a `nextStep`
  pointing at the data refresh. No charge.
- **Joining a running job is still charged.** If a download job for this company is already
  running, the response carries `joinedExisting: true` and the call is charged at the full
  rate — the job will pick up your missing filings.
- **Charged only once the job is queued.** If it cannot be queued you get `503` and are not
  charged.

`filings` in the response counts our filing index: `total`, `downloaded` (PDF on file) and
`missing` (what this job will fetch). New MCA filings we have not indexed yet are not in it —
run the data refresh first.

**Billing**

Charges your `companies.documents.fetch` rate (see the [rate card](https://api.filesure.in/pricing.html)) on `202`. All other
responses are free.

**Sandbox behavior**

`fsk_test_*` keys on a whitelisted CIN return a synthetic `202` with `sandbox: true`. No
unlock is needed, nothing is queued, no charge.

**Common errors**

- `400 INVALID_CIN` — format validation failed
- `402 INSUFFICIENT_BALANCE` — wallet below the document-job fee; nothing queued
- `403 UNLOCK_REQUIRED` — no active unlock for this company; no charge
- `403 NO_ACCESS` — no pricing row for `companies.documents.fetch`
- `404 COMPANY_NOT_FOUND` — we do not hold this company; no charge
- `409 NOTHING_TO_FETCH` — every listed filing already has its PDF; no charge
- `503 DOCUMENT_JOB_QUEUE_UNAVAILABLE` — could not queue; no charge, safe to retry

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `cin` | path | yes | string | 21-character Corporate Identification Number (CIN). |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/companies/U74999HR2015FTC056386/documents/fetch" \
  -X POST \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**202** Document job queued, or joined to one already running

*New job queued*

```json
{
  "data": {
    "cin": "U62013KA2024PTC188236",
    "queued": true,
    "joinedExisting": false,
    "filings": {
      "total": 30,
      "downloaded": 21,
      "missing": 9
    },
    "unlockExpiresAt": "2027-08-16T09:12:40.000Z",
    "progress": "GET /v1/companies/{cin}/unlock"
  },
  "meta": {
    "priceChargedPaisa": 15000,
    "walletBalanceAfterPaisa": 44190
  }
}
```

*Joined a job already running — still charged*

```json
{
  "data": {
    "cin": "U62013KA2024PTC188236",
    "queued": true,
    "joinedExisting": true,
    "filings": {
      "total": 30,
      "downloaded": 21,
      "missing": 9
    },
    "unlockExpiresAt": "2027-08-16T09:12:40.000Z",
    "progress": "GET /v1/companies/{cin}/unlock"
  },
  "meta": {
    "priceChargedPaisa": 15000,
    "walletBalanceAfterPaisa": 29190
  }
}
```

**400** Identifier failed format validation, or unknown idType value

*Identifier doesn't match CIN/FCIN/LLPIN format*

```json
{
  "error": {
    "code": "INVALID_CIN",
    "message": "The provided identifier failed format validation. Expected CIN, FCIN, or LLPIN."
  }
}
```

*Unknown idType query value*

```json
{
  "error": {
    "code": "INVALID_ID_TYPE",
    "message": "Unknown idType. Valid values: cin, fcin, llpin."
  }
}
```

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

**402** Wallet balance is below the endpoint price

```json
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient wallet balance. Please recharge.",
    "balancePaisa": 0,
    "requiredPaisa": 500
  }
}
```

**403** `UNLOCK_REQUIRED` (no active unlock — no charge), `NO_ACCESS` (no pricing row) or `SANDBOX_ONLY` (test key on a non-sandbox CIN).

**

```json
{
  "error": {
    "code": "UNLOCK_REQUIRED",
    "message": "A document job needs an active unlock for this company. Unlock it first; the unlock includes the first download. No charge was made.",
    "nextStep": "POST /v1/companies/{cin}/unlock",
    "unlockPrice": 33000
  }
}
```

**404** We do not hold this company. No charge.

**409** Every listed filing already has its PDF — nothing to fetch, no charge.

**

```json
{
  "error": {
    "code": "NOTHING_TO_FETCH",
    "message": "Every filing we list for this company already has its PDF. Run a data refresh to pick up new MCA filings first. No charge was made.",
    "nextStep": "POST /v1/companies/{cin}/update",
    "filings": {
      "total": 30,
      "downloaded": 30,
      "missing": 0
    }
  }
}
```

**503** Could not queue the document job — not charged, safe to retry.

### Director contact

A director's phone and email, behind a separate per-director unlock (₹299 by default for new accounts; access lasts one year), then read for 5 paisa a call.

#### Unlock a director's contact

`POST /v1/directors/{din}/unlock`

Group: Director contact. Page: https://api.filesure.in/reference/unlock-director-contact.md

Creates a 1-year unlock for this DIN's contact tier (mobile + email) and unlocks [GET /v1/directors/{din}/contact](https://api.filesure.in/reference/get-director-contact.md) for the customer for the next 365 days. The cascade here is structurally different from the company unlock — no background download, no extraction job. Instead:

1. **Hot path** (cached contact <365 days old, mobile or email present): atomic wallet deduction + unlock create + `200 OK`. Sub-200 ms; no MCA fetch.
2. **Cold path** (cached contact stale or missing): triggers an upstream refresh and polls our cache for up to ~10 seconds. If the refresh lands fresh contact within the window, the API deducts the wallet and returns `200`. If it doesn't land, returns `422 CONTACT_NOT_AVAILABLE` with `lastUpdateAttempt` for diagnosis — **wallet is not deducted**.
3. **DIN never seeded:** if we have no record of this DIN at all (its containing CIN was never refreshed), returns `422 CONTACT_NOT_AVAILABLE` with `nextStep: POST /v1/companies/{cin}/unlock` — that endpoint seeds the chain. No upstream call, no deduction.

**Idempotency:** repeating this on a DIN with an active contact unlock returns `409 ALREADY_UNLOCKED` — no double charge.

**Billing**

Pay-gate. Charges the director-contact unlock fee from your wallet (your `directors.unlock` rate, see the [rate card](https://api.filesure.in/pricing.html)). Wallet must have sufficient balance. The wallet-deduction guard ensures: if the upstream refresh fails or times out, wallet is not deducted.

**Sandbox behavior**

`fsk_test_*` keys on a sandbox-whitelisted DIN return `200 OK` with a synthetic unlock (`{ unlocked: true, sandbox: true }`) — no real writes, no upstream refresh, no real contact data ever leaked. Test keys on non-sandbox DINs return `403 SANDBOX_ONLY`.

**Common errors**

- `503 SERVICE_UNAVAILABLE` — director-contact unlock disabled by ops (`DIRECTOR_CONTACT_UNLOCK_ENABLED=false`). Wallet **not** deducted
- `400 INVALID_DIN` — DIN failed 8-digit format validation
- `402 INSUFFICIENT_BALANCE` — wallet under the unlock price
- `403 NO_ACCESS` — no pricing row for `directors.unlock`
- `403 SANDBOX_ONLY` — test key on a non-sandbox DIN
- `409 ALREADY_UNLOCKED` — unlock already exists for this DIN
- `422 CONTACT_NOT_AVAILABLE` — upstream refresh failed/timed out, OR DIN not in our cache. Wallet **not** deducted

Plus the global auth/wallet/permission errors — see the [error codes table](https://api.filesure.in/reference/start-here/responses-and-errors.md).

**See also**

- [Cascade diagram](https://api.filesure.in/reference/start-here/how-filesure-data-works.md) (visual: hot path vs cold path with the ~10s upstream-refresh poll)
- [Get director contact unlock status](https://api.filesure.in/reference/get-director-contact-unlock.md)
- [Get director contact](https://api.filesure.in/reference/get-director-contact.md) (the gated read)
- [Unlock a company](https://api.filesure.in/reference/unlock-company.md) (seeds the chain when 422 nextStep is given)

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `din` | path | yes | string | 8-digit Director Identification Number (DIN). Test keys (`fsk_test_*`) can only call DINs in the **Sandbox** allowlist — see the Sandbox tag in the sidebar for the full list. |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/directors/00002157/unlock" \
  -X POST \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** Unlock created (live key) or sandbox synthetic (test key on sandbox DIN).

Fields:

- `data`: object
  - `din`: string
  - `unlocked`: boolean
  - `unlockedAt`: string (date-time), optional. When the unlock was created. `null` for sandbox or no-unlock states.
  - `expiresAt`: string (date-time), optional. 1 year after `unlockedAt`. `null` for sandbox or no-unlock states.
  - `unlockPrice`: integer, optional. Per-unlock price in paisa (₹ × 100). `null` if no pricing exists for this customer.
  - `sandbox`: boolean, optional. Present only on synthetic sandbox responses (test key + sandbox DIN).
  - `contactUpdatedAt`: string (date-time), optional. When this DIN's cached contact was last refreshed. Use it to self-detect stale contact data (we treat anything <365 days old as fresh and won't re-trigger refresh on the next unlock attempt). `null` for sandbox.
  - `lastUpdateAttempt`: object, optional. Latest upstream refresh attempt status. Surfaces success/failure diagnostics. `null` for sandbox or when no refresh has ever been attempted.
    - `status`: string, optional. `success` or `error`.
    - `timestamp`: string (date-time), optional
    - `errorMessage`: string, optional
- `meta`: object

**400** DIN failed format validation (must be 8 numeric digits)

```json
{
  "error": {
    "code": "INVALID_DIN",
    "message": "DIN must be 8 numeric digits."
  }
}
```

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

**402** Wallet balance is below the endpoint price

```json
{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient wallet balance. Please recharge.",
    "balancePaisa": 0,
    "requiredPaisa": 500
  }
}
```

**403** `NO_ACCESS` (no pricing record) or `SANDBOX_ONLY` (test key on non-sandbox DIN).

*Customer has no pricing for directors.unlock*

```json
{
  "error": {
    "code": "NO_ACCESS",
    "message": "No access to endpoint 'directors.unlock'. Contact support to enable access.",
    "endpoint": "directors.unlock",
    "catalogPricePaisa": 29900
  }
}
```

*Test key on a non-sandbox DIN*

```json
{
  "error": {
    "code": "SANDBOX_ONLY",
    "message": "A test key only works on the sandbox companies and directors. They are listed in this response and at GET /v1/sandbox. Use one of those, or a live key.",
    "sandboxCompanies": [
      {
        "cin": "U74999HR2015FTC056386",
        "company": "CARS24 SERVICES PRIVATE LIMITED",
        "knownAs": "Cars24"
      },
      {
        "cin": "L93030DL2010PLC198141",
        "company": "ETERNAL LIMITED",
        "knownAs": "Eternal, formerly Zomato"
      }
    ],
    "sandboxDirectors": [
      {
        "din": "11692472",
        "fullName": "NILESH KASHINATH HIWALE"
      }
    ],
    "nextStep": "GET /v1/sandbox"
  }
}
```

**409** Active contact unlock already exists for this DIN. No double charge.

**422** Contact data could not be made available (refresh failed/timed out, or DIN row missing). Wallet is not deducted.

*DIN never seen by our master-data chain*

```json
{
  "error": {
    "code": "CONTACT_NOT_AVAILABLE",
    "message": "We don't have contact data for this DIN yet. Update a containing company first.",
    "nextStep": "POST /v1/companies/:cin/unlock"
  }
}
```

*Upstream refresh did not land contact in the polling window*

```json
{
  "error": {
    "code": "CONTACT_NOT_AVAILABLE",
    "message": "Contact refresh did not return contact data within the allowed window.",
    "lastUpdateAttempt": {
      "status": "error",
      "timestamp": "2026-05-01T07:30:00.000Z",
      "errorMessage": "No data found in parsed resStr"
    }
  }
}
```

#### Get director contact unlock status

`GET /v1/directors/{din}/unlock`

Group: Director contact. Page: https://api.filesure.in/reference/get-director-contact-unlock.md

**What it returns**

Unlock state for this DIN's contact tier, plus freshness metadata (`contactUpdatedAt` + `lastUpdateAttempt`) so customers can self-detect stale data. Three branches:

- **Active unlock:** `unlocked: true`, `unlockedAt`, `expiresAt`, plus `contactUpdatedAt` and `lastUpdateAttempt` so customers can self-detect stale data.
- **No unlock:** `unlocked: false`, `unlockPrice` (or `null` if customer has no pricing for `directors.unlock`). Same freshness metadata included.
- **Sandbox** (test key + sandbox DIN): synthetic `unlocked: true, sandbox: true`. No real contact metadata leaked.

Read-only — doesn't trigger an upstream refresh or write to our cache.

**Billing**

Free. No wallet deduction; not subject to pricing rows.

**Sandbox behavior**

Test keys (`fsk_test_*`) on a sandbox-whitelisted DIN return the synthetic branch above. Outside the whitelist: `403 SANDBOX_ONLY`.

**Common errors**

- `400 INVALID_DIN` — DIN failed 8-digit format validation

Plus the global auth/permission errors — see the [error codes table](https://api.filesure.in/reference/start-here/responses-and-errors.md).

**See also**

- [Unlock director's contact](https://api.filesure.in/reference/unlock-director-contact.md)
- [Get director contact](https://api.filesure.in/reference/get-director-contact.md)

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `din` | path | yes | string | 8-digit Director Identification Number (DIN). Test keys (`fsk_test_*`) can only call DINs in the **Sandbox** allowlist — see the Sandbox tag in the sidebar for the full list. |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/directors/00002157/unlock" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** Unlock state for this DIN.

*Active unlock with fresh contact data*

```json
{
  "data": {
    "din": "00002157",
    "unlocked": true,
    "unlockedAt": "2026-05-01T07:30:00.000Z",
    "expiresAt": "2027-05-01T07:30:00.000Z",
    "unlockPrice": 29900,
    "contactUpdatedAt": "2026-04-15T12:00:00.000Z",
    "lastUpdateAttempt": {
      "status": "success",
      "timestamp": "2026-04-15T12:00:00.000Z"
    }
  },
  "meta": {}
}
```

*Customer hasn't unlocked this DIN's contact*

```json
{
  "data": {
    "din": "00002157",
    "unlocked": false,
    "unlockPrice": 29900,
    "contactUpdatedAt": "2026-04-15T12:00:00.000Z",
    "lastUpdateAttempt": {
      "status": "success",
      "timestamp": "2026-04-15T12:00:00.000Z"
    }
  },
  "meta": {}
}
```

**400** DIN failed format validation (must be 8 numeric digits)

```json
{
  "error": {
    "code": "INVALID_DIN",
    "message": "DIN must be 8 numeric digits."
  }
}
```

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

**403** Test key on a non-sandbox DIN.

#### Get director contact

`GET /v1/directors/{din}/contact`

Group: Director contact. Page: https://api.filesure.in/reference/get-director-contact.md

**What it returns**

Director contact details — email, phone, and any other PII fields the MCA contact tier carries for this DIN. Returned only when the customer has an active contact-unlock for this DIN; otherwise returns the unlock-status JSON.

Director-contact data is sourced from a separate refresh path, **not** the company download cascade. If our cached contact is fresh (<365 days old), the unlock returns instantly. Otherwise the unlock POST triggers an upstream refresh and polls for up to ~10 seconds; see [POST /v1/directors/{din}/unlock](https://api.filesure.in/reference/unlock-director-contact.md) for how that works.

**Billing**

Unlock-gated. The contact unlock is per-DIN, separate from the company-level unlock. Without an active contact unlock for this DIN, this endpoint returns `200 { unlocked: false, unlockPrice }` instead of the contact data, with no charge. Inside the unlock window (1 year), each call is metered at your `directors.contact` rate (see the [rate card](https://api.filesure.in/pricing.html)).

**Sandbox behavior**

Test keys (`fsk_test_*`) on a sandbox-whitelisted DIN return a synthetic unlock state and the cached contact when present. Outside the sandbox: `403 SANDBOX_ONLY`.

**Common errors**

- `400 INVALID_DIN` — DIN failed 8-digit format validation
- `404` — director not found in our cache. The contact unlock won't seed the row either (it'll return `422 CONTACT_NOT_AVAILABLE`); instead, unlock a containing company first via [POST /v1/companies/{cin}/unlock](https://api.filesure.in/reference/unlock-company.md), which seeds the whole director chain, then retry the contact unlock for this DIN.

Plus the global auth/wallet/permission errors — see the [error codes table](https://api.filesure.in/reference/start-here/responses-and-errors.md).

**See also**

- [Get director profile](https://api.filesure.in/reference/get-director-master.md) (no unlock; non-PII fields)
- [Unlock director's contact](https://api.filesure.in/reference/unlock-director-contact.md)
- [Get director contact unlock status](https://api.filesure.in/reference/get-director-contact-unlock.md)

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `din` | path | yes | string | 8-digit Director Identification Number (DIN). Test keys (`fsk_test_*`) can only call DINs in the **Sandbox** allowlist — see the Sandbox tag in the sidebar for the full list. |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/directors/00002157/contact" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** Contact data (when unlocked) or unlock status (when not unlocked).

*Sandbox DIN — contact unlocked (truncated)*

```json
{
  "data": {
    "din": "00002157",
    "mobileNumber": "+91 98xxxxxx00",
    "emailAddress": "example@cars24.in"
  },
  "meta": {}
}
```

*Customer hasn't unlocked this DIN's contact yet*

```json
{
  "data": {
    "unlocked": false,
    "unlockPrice": 29900
  },
  "meta": {}
}
```

### Your account

Wallet balance and usage, the wallet ledger, top-ups, your billing profile and GST invoices. All free, on live and test keys alike.

#### Get wallet + usage

`GET /v1/account/usage`

Group: Your account. Page: https://api.filesure.in/reference/get-account-usage.md

**What it returns**

Your current wallet balance plus a per-endpoint breakdown of usage in the last 30 days. Money values are integers in **paisa** (1/100 of an INR rupee — e.g. `balancePaisa: 1000000` is ₹10,000.00). The `byEndpoint` array is sorted by `spendPaisa` descending and only contains endpoints actually called in the window — endpoints with zero usage are absent.

Use this endpoint to surface "Wallet: ₹XYZ" + "Top spend: companies.master at ₹ABC" in your own dashboards. The 30-day window is rolling.

**Billing**

Free. No wallet deduction; not subject to pricing rows. Works with both `fsk_live_*` and `fsk_test_*` keys.

**Sandbox behavior**

Test keys see the same response shape with the same wallet (test/live keys share one wallet per customer). Sandbox-only test calls don't deduct, so they don't show up in `spendPaisa` totals — but they DO appear in usage logs with `priceChargedPaisa: 0`.

**Common errors**

Just the global auth errors — see the [error codes table](https://api.filesure.in/reference/start-here/responses-and-errors.md).

**See also**

- The [Developer Portal usage page](https://api.filesure.in/portal/dashboard/usage) for an interactive view of the same data

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/account/usage" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** Wallet balance and 30-day usage summary.

*Active customer with realistic usage (truncated)* Real customers may show 5–10 endpoints in `byEndpoint`; example shows top 3 spenders.

```json
{
  "data": {
    "wallet": {
      "balancePaisa": 873500,
      "currency": "INR"
    },
    "usage": {
      "last30Days": {
        "totalCalls": 2340,
        "totalSpendPaisa": 126500,
        "byEndpoint": [
          {
            "endpoint": "companies.master",
            "calls": 412,
            "spendPaisa": 41200
          },
          {
            "endpoint": "companies.unlock",
            "calls": 3,
            "spendPaisa": 66000
          },
          {
            "endpoint": "companies.filings.download",
            "calls": 1925,
            "spendPaisa": 19250
          }
        ]
      }
    }
  },
  "meta": {
    "generatedAt": "2026-05-01T07:45:12.000Z"
  }
}
```

*New customer with no spend yet*

```json
{
  "data": {
    "wallet": {
      "balancePaisa": 1000000,
      "currency": "INR"
    },
    "usage": {
      "last30Days": {
        "totalCalls": 0,
        "totalSpendPaisa": 0,
        "byEndpoint": []
      }
    }
  },
  "meta": {
    "generatedAt": "2026-05-01T07:45:12.000Z"
  }
}
```

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

**403** `ACCOUNT_DISABLED` — the customer account associated with this API key has been deactivated. Contact support to re-enable.

#### Your rate card

`GET /v1/account/pricing`

Group: Your account. Page: https://api.filesure.in/reference/get-account-pricing.md

**What it returns**

The price your account pays for each endpoint, in **paisa**, read from the same pricing rows every billed call is charged from, so what you see here is exactly what a call will cost. One row per endpoint key you hold a price for; an endpoint with no row is one your account cannot call (`403 NO_ACCESS`). `defaultPricePaisa` is the published rate-card price for that endpoint, so you can see where your account has a negotiated rate; it is `null` for endpoints not on the public rate card.

Use it to show your own users what an action will cost before they take it. Unlocks appear under their keys (`companies.unlock`, `directors.unlock`) at the unlock fee; per-call endpoints at the per-call fee.

**Billing**

Free. No wallet deduction; not subject to pricing rows.

**Sandbox behavior**

Test keys see the same rates as live keys (one rate card per account); sandbox calls are never charged regardless.

**Common errors**

Just the global auth errors, see the [error codes table](https://api.filesure.in/reference/start-here/responses-and-errors.md).

**See also**

- [Billing and the wallet](https://api.filesure.in/reference/start-here/billing-and-the-wallet.md)
- [Get wallet + usage](https://api.filesure.in/reference/get-account-usage.md)

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/account/pricing" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** The caller's effective rates.

```json
{
  "data": {
    "currency": "INR",
    "rates": [
      {
        "endpoint": "companies.documents.fetch",
        "pricePerCallPaisa": 15000,
        "defaultPricePaisa": 15000,
        "effectiveFrom": "2026-09-14T00:00:00.000Z"
      },
      {
        "endpoint": "companies.master",
        "pricePerCallPaisa": 500,
        "defaultPricePaisa": 500,
        "effectiveFrom": "2026-07-27T00:00:00.000Z"
      },
      {
        "endpoint": "companies.unlock",
        "pricePerCallPaisa": 33000,
        "defaultPricePaisa": 33000,
        "effectiveFrom": "2026-07-27T00:00:00.000Z"
      },
      {
        "endpoint": "companies.update",
        "pricePerCallPaisa": 100,
        "defaultPricePaisa": 100,
        "effectiveFrom": "2026-09-14T00:00:00.000Z"
      }
    ]
  },
  "meta": {
    "requestId": "…",
    "generatedAt": "2026-09-15T09:30:00.000Z"
  }
}
```

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

#### Wallet ledger

`GET /v1/account/wallet/transactions`

Group: Your account. Page: https://api.filesure.in/reference/get-wallet-transactions.md

Every credit to your wallet, newest first: top-ups, refunds and manual credits. Charges are not
ledger rows; they are usage, and appear in [usage](https://api.filesure.in/reference/get-account-usage.md) and on
every metered response as `meta.priceChargedPaisa`.

`type` is `recharge`, `refund` or `admin_credit`. `balanceAfterPaisa` is the wallet balance right
after that row landed, so the ledger reads as a running statement. `referenceId` links a top-up
to its recharge order or a refund to what it refunds.

**Billing:** free. **Sandbox:** same response on a test key; test and live keys share one wallet.

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `page` | query | no | integer | (default 1, 1) |
| `limit` | query | no | integer | (default 50, 1 to 200) |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/account/wallet/transactions?limit=3" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** Ledger rows, newest first.

```json
{
  "data": [
    {
      "id": "6aa7a0c1b22e2991f01372ff",
      "type": "recharge",
      "source": "zoho",
      "amountPaisa": 1000000,
      "balanceAfterPaisa": 1129390,
      "referenceId": "pay_0123456789",
      "metadata": null,
      "createdAt": "2026-09-10T08:12:40.000Z"
    },
    {
      "id": "6a9db6f052dc117ec46157c2",
      "type": "refund",
      "source": "system",
      "amountPaisa": 15000,
      "balanceAfterPaisa": 129390,
      "referenceId": null,
      "metadata": {
        "reason": "Refund of a charge that did no work"
      },
      "createdAt": "2026-09-06T18:55:02.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 2,
    "totalPages": 1,
    "requestId": "…"
  }
}
```

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

#### Top up the wallet

`POST /v1/account/wallet/recharge`

Group: Your account. Page: https://api.filesure.in/reference/create-wallet-recharge.md

Creates a payment order for the amount of credit you want and returns the session that opens the
hosted checkout. GST at 18% is added on top: `amountPaisa` is the credit you receive,
`totalPaisa` is what you pay. Credit lands in the wallet when the payment is confirmed; read
[recharge status](https://api.filesure.in/reference/get-wallet-recharge-status.md) to follow it,
and expect a GST invoice against the order once it is paid.

Requires a live key (`403 SANDBOX_NOT_ALLOWED` on a test key) and a completed
[billing profile](https://api.filesure.in/reference/get-billing-profile.md), since the invoice needs it.
Credit must be between ₹10,000 and ₹10,00,000 per order.

**Billing:** creating the order is free; you pay at the checkout.

##### Request body

JSON, required.

- `amountPaisa`: integer. Credit to add, in paisa. ₹10,000 to ₹10,00,000.

```json
{
  "amountPaisa": 1000000
}
```

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/account/wallet/recharge" \
  -X POST \
  -H "x-api-key: fsk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"amountPaisa":1000000}'
```

##### Responses

**200** Payment order created; open the checkout with `paymentsSessionId`.

```json
{
  "data": {
    "orderId": "6aa7a0c1b22e2991f01372ff",
    "paymentsSessionId": 2000000012345678800,
    "accountId": "60064718354",
    "amountPaisa": 1000000,
    "gstPaisa": 180000,
    "totalPaisa": 1180000
  },
  "meta": {
    "requestId": "…"
  }
}
```

**400** `INVALID_AMOUNT` (not a positive integer) or `AMOUNT_OUT_OF_RANGE` (outside ₹10,000 to ₹10,00,000).

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

**403** `SANDBOX_NOT_ALLOWED` on a test key, or `BILLING_INCOMPLETE` until the billing profile is set.

#### Recharge status

`GET /v1/account/wallet/recharge/{orderId}/status`

Group: Your account. Page: https://api.filesure.in/reference/get-wallet-recharge-status.md

The state of one top-up order: `pending` until the payment is confirmed, then `paid` (credit is in
the wallet), or `failed` / `expired`. Read-only; polling it never credits anything. A payment that
was confirmed but has not yet shown here is picked up by a periodic check within about fifteen
minutes.

**Billing:** free.

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `orderId` | path | yes | string | The `orderId` returned when the order was created. |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/account/wallet/recharge/<orderId from the recharge response>/status" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** Order state.

```json
{
  "data": {
    "orderId": "6aa7a0c1b22e2991f01372ff",
    "status": "paid",
    "amountPaisa": 1000000,
    "gstPaisa": 180000,
    "totalPaisa": 1180000,
    "currency": "INR",
    "paymentsSessionId": 2000000012345678800,
    "createdAt": "2026-09-10T08:12:40.000Z",
    "paidAt": "2026-09-10T08:14:03.000Z"
  },
  "meta": {
    "requestId": "…"
  }
}
```

**400** `INVALID_ORDER_ID`

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

**404** `RECHARGE_NOT_FOUND`: no such order on your account.

#### Billing profile

`GET /v1/account/billing`

Group: Your account. Page: https://api.filesure.in/reference/get-billing-profile.md

The name, address and tax details your GST invoices are issued to. `null` until you set it with
[PUT /v1/account/billing](https://api.filesure.in/reference/put-billing-profile.md); a top-up needs it.

**Billing:** free.

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/account/billing" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** The profile, or `billing: null`.

```json
{
  "data": {
    "billing": {
      "billingType": "business",
      "businessName": "Example Analytics Private Limited",
      "contactName": "Priya Nair",
      "email": "finance@example.in",
      "phone": "+91 98xxxxxx00",
      "gstin": "27AAAAA0000A1Z5",
      "address": "4th Floor, 12 MG Road",
      "city": "Mumbai",
      "state": "27",
      "zipCode": "400001",
      "country": "India"
    }
  },
  "meta": {
    "requestId": "…"
  }
}
```

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

#### Set the billing profile

`PUT /v1/account/billing`

Group: Your account. Page: https://api.filesure.in/reference/put-billing-profile.md

Replaces the billing profile. `billingType` is `business` or `consumer`. A business must give
`businessName`, a valid `gstin` and an `address`; the state of supply is read from the GSTIN. A
consumer in India must give a two-digit `state` code. `contactName` is always required; `email`,
`phone`, `city` and `zipCode` are optional. Values are trimmed and the GSTIN upper-cased before
saving; the response returns the saved profile.

**Billing:** free.

##### Request body

JSON, required.

```json
{
  "billingType": "business",
  "businessName": "Example Analytics Private Limited",
  "contactName": "Priya Nair",
  "email": "finance@example.in",
  "gstin": "27AAAAA0000A1Z5",
  "address": "4th Floor, 12 MG Road",
  "city": "Mumbai",
  "zipCode": "400001",
  "country": "India"
}
```

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/account/billing" \
  -X PUT \
  -H "x-api-key: fsk_test_..." \
  -H "Content-Type: application/json" \
  -d '{"billingType":"business","businessName":"Example Analytics Private Limited","contactName":"Priya Nair","email":"finance@example.in","gstin":"27AAAAA0000A1Z5","address":"4th Floor, 12 MG Road","city":"Mumbai","zipCode":"400001","country":"India"}'
```

##### Responses

**200** The saved profile.

```json
{
  "data": {
    "billing": {
      "billingType": "business",
      "businessName": "Example Analytics Private Limited",
      "contactName": "Priya Nair",
      "email": "finance@example.in",
      "gstin": "27AAAAA0000A1Z5",
      "address": "4th Floor, 12 MG Road",
      "city": "Mumbai",
      "state": "27",
      "zipCode": "400001",
      "country": "India"
    }
  },
  "meta": {
    "requestId": "…"
  }
}
```

**400** `INVALID_BILLING`, `INVALID_BILLING_TYPE`, `MISSING_CONTACT_NAME`, `MISSING_BUSINESS_NAME`, `MISSING_GSTIN`, `INVALID_GSTIN`, `MISSING_ADDRESS`, `MISSING_STATE` or `INVALID_STATE`; the message names the field.

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

#### Top-up history

`GET /v1/account/recharges`

Group: Your account. Page: https://api.filesure.in/reference/get-recharges.md

Every top-up order on your account, newest first, with its payment state and invoice state.
`canDownloadInvoice` is `true` once the GST invoice for a paid order has been issued; fetch it
from [the invoice endpoint](https://api.filesure.in/reference/get-invoice-pdf.md).

**Billing:** free.

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `page` | query | no | integer | (default 1, 1) |
| `limit` | query | no | integer | (default 50, 1 to 200) |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/account/recharges?limit=3" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** Orders, newest first.

```json
{
  "data": [
    {
      "orderId": "6aa7a0c1b22e2991f01372ff",
      "amountPaisa": 1000000,
      "gstPaisa": 180000,
      "totalPaisa": 1180000,
      "status": "paid",
      "invoiceStatus": "invoiced",
      "invoiceNumber": "FS/2026-27/000123",
      "invoiceDate": "2026-09-10",
      "canDownloadInvoice": true,
      "createdAt": "2026-09-10T08:12:40.000Z",
      "paidAt": "2026-09-10T08:14:03.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "totalPages": 1,
    "requestId": "…"
  }
}
```

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

#### Download a GST invoice

`GET /v1/account/invoices/{rechargeId}/pdf`

Group: Your account. Page: https://api.filesure.in/reference/get-invoice-pdf.md

The GST invoice for one paid top-up, as a PDF. This is the one account endpoint that does not
return the JSON envelope: the response body is the file, with a `Content-Disposition` filename
of the invoice number.

**Billing:** free.

##### Parameters

| Name | In | Required | Type | Description |
|---|---|---|---|---|
| `rechargeId` | path | yes | string | The `orderId` of a paid top-up. |

##### Request example

Sandbox identifiers with a test key; nothing is charged.

```bash
curl "https://api.filesure.in/v1/account/invoices/<rechargeId from the recharges list>/pdf" \
  -H "x-api-key: fsk_test_..."
```

##### Responses

**200** The invoice PDF.

**400** `INVALID_ORDER_ID`

**401** API key missing, invalid, or revoked

*Header absent*

```json
{
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key is required. Pass it via the x-api-key header."
  }
}
```

*Key not recognised*

```json
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid."
  }
}
```

*Key revoked*

```json
{
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API key has been revoked."
  }
}
```

**404** `RECHARGE_NOT_FOUND`: no such order on your account.

**409** `INVOICE_NOT_READY`: the order is not paid yet, or its invoice has not been issued yet.

**503** `INVOICING_UNAVAILABLE`: invoicing is temporarily unavailable; try again later.