# 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**.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.orbitfin.ai/orbit-api-reference/api/bulk-entity-lookup-1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.