# OpenFIGI API Summary: Mapping, Search, and Filter Endpoints

This Markdown summary covers the **API Guidelines**, **Request Format**, and **Sample Request -> Sample Response** for the key OpenFIGI endpoints: Mapping, Search, and Filter. Information is based on the official documentation as of December 1, 2025.

## Mapping Endpoint

### API Guidelines
- **Endpoint**: `POST /v3/mapping`
- **Purpose**: Map third-party identifiers (e.g., ISIN, TICKER) to FIGIs (Financial Instrument Global Identifiers).
- **Request Format**: JSON array of objects (mapping jobs). Each job requires `idType` and `idValue`. Optional filters: `exchCode`, `micCode`, `currency`, `marketSecDes`, `securityType`, `securityType2`, `includeUnlistedEquities`, `optionType`, `strike`, `contractSize`, `coupon`, `expiration`, `maturity`, `stateCode`.
- **Key Parameters**:
  - `idType` (String, Required): Identifier type (e.g., `ID_BB_GLOBAL`, `TICKER`, `ID_ISIN`).
  - `idValue` (String/Number, Required): The identifier value.
  - `exchCode` (String, Optional): Exchange code (mutually exclusive with `micCode`).
  - `micCode` (String, Optional): Market Identification Code (mutually exclusive with `exchCode`).
  - Range parameters (e.g., `strike`, `expiration`): Arrays like `[a, b]` or `[a, null]` for intervals.
  - `includeUnlistedEquities` (Boolean, Optional): Defaults to `false`.
- **Limits**:
  - Without API key: Max 5 jobs per request.
  - With API key: Max 100 jobs per request.
- **Rate Limits**:
  - Without API key: 25 requests/minute.
  - With API key: 25 requests/6 seconds.
- **Authentication**: Include `X-OPENFIGI-APIKEY` header for higher limits.

### Sample Request
```json
[
    { "idType": "ID_BB_GLOBAL", "idValue": "BBG000BLNNH6" },
    { "idType": "TICKER", "idValue": "IBM", "exchCode": "US" },
    { "idType": "BASE_TICKER", "idValue": "TSLA 10 C100", "securityType2": "Option", "expiration": ["2018-10-01", "2018-12-01"] }
]
```

### Sample Response
```json
[{
    "data": [{
        "figi": "BBG000BLNNH6",
        "securityType": "Common Stock",
        "marketSector": "Equity",
        "ticker": "IBM",
        "name": "INTL BUSINESS MACHINES CORP",
        "exchCode": "US",
        "shareClassFIGI": "BBG001S5S399",
        "compositeFIGI": "BBG000BLNNH6",
        "securityType2": "Common Stock",
        "securityDescription": "IBM"
    }]
}]
```

## Search Endpoint

### API Guidelines
- **Endpoint**: `POST /v3/search`
- **Purpose**: Keyword-based search for FIGIs with optional filters; supports pagination.
- **Request Format**: JSON object with optional `query` (keywords) and filters (same as Mapping). Use `start` for pagination.
- **Key Parameters**:
  - `query` (String, Optional): Search keywords (e.g., "ibm").
  - `start` (String, Optional): Pagination token from previous `next` field.
  - All Mapping filters supported (e.g., `exchCode`, `securityType`, `optionType`).
- **Limits**:
  - Max results: 15,000.
  - Max per page: 100.
  - Max pages: 150.
- **Rate Limits**:
  - Without API key: 5 requests/minute.
  - With API key: 20 requests/minute.
- **Pagination**: Response includes `next` token; use as `start` in next request.
- **Authentication**: Same as Mapping.

### Sample Request
```json
{
    "query": "ibm",
    "exchCode": "US"
}
```

### Sample Response
```json
{
    "data": [
        {
            "figi": "BBG000BLNNH6",
            "name": "INTL BUSINESS MACHINES CORP",
            "ticker": "IBM",
            "exchCode": "US",
            "compositeFIGI": "BBG000BLNNH6",
            "securityType": "Common Stock",
            "marketSector": "Equity",
            "shareClassFIGI": "BBG001S5S399",
            "securityType2": "Common Stock",
            "securityDescription": "IBM"
        }
    ],
    "next": "QW9JSVFEOFMrQ3hDUWtjd01ERTRTMHhhUXpBPSAx.3AG33VCsv54AsUl5fGHehSytWPuWLJxf0t8VL3YXuJh="
}
```

## Filter Endpoint

### API Guidelines
- **Endpoint**: `POST /v3/filter`
- **Purpose**: Filter-based search for FIGIs (no keywords required); results sorted alphabetically by FIGI, includes total count.
- **Request Format**: JSON object with optional `query` and filters (same as Search/Mapping). Use `start` for pagination.
- **Key Parameters**: Identical to Search (`query`, `start`, and all Mapping filters).
- **Limits**: Same as Search (15,000 max results, 100/page, 150 pages).
- **Rate Limits**: Same as Search (5/min without key, 20/min with key).
- **Pagination**: Same as Search; response includes `total` count.
- **Authentication**: Same as Mapping.

### Sample Request
```json
{
    "exchCode": "US"
}
```

### Sample Response
```json
{
    "data": [
        {
            "figi": "BBG000BLNNH6",
            "name": "INTL BUSINESS MACHINES CORP",
            "ticker": "IBM",
            "exchCode": "US",
            "compositeFIGI": "BBG000BLNNH6",
            "securityType": "Common Stock",
            "marketSector": "Equity",
            "shareClassFIGI": "BBG001S5S399",
            "securityType2": "Common Stock",
            "securityDescription": "IBM"
        }
    ],
    "next": "QW9JSVFEOFMrQ3hDUWtjd01ERTRTMHhhUXpBPSAx.3AG33VCsv54AsUl5fGHehSytWPuWLJxf0t8VL3YXuJh=",
    "total": 29930312
}
```