# 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