> For the complete documentation index, see [llms.txt](https://docs.orbitfin.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.orbitfin.ai/orbit-api-reference/api/bulk-entity-lookup-1.md).

# Bulk Entity Lookup

#### Endpoint

```
POST /v1/company_report/company_search_batch
```

[**Try it out in API Playground →**](https://api.orbitfin.ai/docs#/company/company_search_batch_v1_company_report_company_search_batch_post)

#### Request

**Headers**

| Name           | Type   | Required | Description        |
| -------------- | ------ | -------- | ------------------ |
| `Content-Type` | string | Yes      | `application/json` |
| `X-API-KEY`    | string | Yes      | your-api-key       |

**Request Body Parameters**

| Parameter        | Type    | Required | Description                                                                        |
| ---------------- | ------- | -------- | ---------------------------------------------------------------------------------- |
| `country`        | string  | No       | country code (e.g., `US`, `GB`, `JP`)                                              |
| `market_cap_usd` | object  | No       | Market capitalization range in USD (e.g., `{"min": 1000000, "max": 10000000}`)     |
| `sector`         | string  | No       | Unique identifier for the company's primary industry classification                |
| `exchange`       | string  | No       | Exchange Code for exchange (e.g., `XNAS`, `XLON`)                                  |
| `limit`          | integer | No       | Number of results per page (default: `20`, max: `100`)                             |
| `offset`         | integer | No       | Pagination offset (default: `0`)                                                   |
| `order`          | string  | No       | Sort order: `market_cap_desc` (default), `market_cap_asc`, `name_asc`, `name_desc` |

> **Note:** Options for `market_cap_usd`, `exchange`, `country`, and `sector` are included in **Appendix B: Metainfo**.

**Example Request**

```bash
curl -X 'POST' \
  'https://api.orbitfin.ai/v1/company_report/company_search_batch' \
  -H 'accept: application/json' \
  -H 'X-API-KEY: <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
  "country": "US",
  "market_cap_usd": {
    "min": 1000000000,
    "max": 10000000000
  },
  "sector": "",
  "limit": 20,
  "offset": 0,
  "order": "market_cap_desc",
  "exchange": "XNAS"
}'
```

#### Response

**Response Fields**

**Top-Level Fields**

| Field         | Type        | Description                                                 |
| ------------- | ----------- | ----------------------------------------------------------- |
| `status_code` | integer     | HTTP status code (200 for success)                          |
| `data`        | object      | Container object holding search results and pagination info |
| `detail`      | string/null | Additional error details (null on success)                  |
| `message`     | string      | Response status message                                     |

**Data Object**

| Field        | Type   | Description                                            |
| ------------ | ------ | ------------------------------------------------------ |
| `companies`  | array  | Array of company objects matching the search criteria  |
| `pagination` | object | Pagination metadata for navigating through result sets |

**Company Object (`data.companies[]`)**

| Field               | Type   | Description                                                          |
| ------------------- | ------ | -------------------------------------------------------------------- |
| `orbit_entity_id`   | string | Unique identifier for the company entity in the Orbit system         |
| `name`              | string | Official registered name of the company                              |
| `png_logo_path`     | string | URL to the company's logo image in PNG format                        |
| `country`           | string | ISO 3166-1 alpha-2 country code where the primary listing is located |
| `exchange`          | string | Market Identifier Code (MIC) of the primary exchange                 |
| `market_cap_usd`    | number | Current market capitalization in US dollars                          |
| `primary_sector_id` | string | Unique identifier for the company's primary industry classification  |
| `lei`               | string | Legal Entity Identifier (LEI) - 20-character unique identifier       |
| `cik`               | string | Central Index Key (CIK) assigned by the U.S. SEC                     |
| `primary_isin`      | string | Primary ISIN code for the company's equity                           |
| `primary_ticker`    | string | Primary stock ticker symbol for the company's equity                 |

**Pagination Object (`data.pagination`)**

| Field      | Type    | Description                                                                |
| ---------- | ------- | -------------------------------------------------------------------------- |
| `total`    | integer | Total number of companies matching the search criteria across all pages    |
| `limit`    | integer | Maximum number of results returned per page                                |
| `offset`   | integer | Number of results skipped from the beginning (used for pagination)         |
| `has_more` | boolean | Indicates whether additional results are available beyond the current page |

**Example Response**

```json
{
  "status_code": 200,
  "data": {
    "companies": [
      {
        "orbit_entity_id": "1-4295907168",
        "name": "MICROSOFT CORP",
        "png_logo_path": "https://ot-cdn.s3.us-west-2.amazonaws.com/company-logos/v1/a33d7aebcf9e4b3ca05ed6df6ecf4d16.png",
        "country": "AT",
        "exchange": "XWBO",
        "market_cap_usd": 3901297294155.35,
        "primary_sector_id": "1-4294952829",
        "lei": "INR2EJN1ERAN0W5ZP974",
        "cik": "0000789019",
        "primary_isin": "US5949181045",
        "primary_ticker": "MSFT"
      }
    ],
    "pagination": {
      "total": 150,
      "limit": 20,
      "offset": 0,
      "has_more": true
    }
  },
  "detail": null,
  "message": "Search successful"
}
```

#### Error Handling

All endpoints follow the standard error response format. When an error occurs, the API returns an appropriate HTTP status code along with a structured error response.

For detailed information about error codes, response formats, and troubleshooting guidelines, please refer to **Appendix A: Error Code Reference**.