> ## Documentation index
> Fetch the complete documentation index at: https://docs.leadmcp.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get the company schema

`GET /companies/schema`

Returns every public company column and every company filter key. Free.

Returns every public company column and every company filter key. Free.

Cost: Free.

## Response

- `columns` | array of SchemaColumn | required. The public columns, in the default order.
  - `name` | string | required. The column name used in requests, files and rows.
  - `type` | enum | required. The value type of the column. The list is frozen. Values: `string`, `integer`, `number`, `boolean`, `date`, `month`, `array`, `object`.
  - `description` | string | required. One sentence about what the column holds.
  - `format` | string | optional. The value format, for example `YYYY-MM` or an ISO-2 slug.
  - `nullable` | boolean | optional. True when the column can be null. A null never matches a value key.
  - `closed_list` | boolean | optional. True when the column takes values from a closed slug list.
  - `values_route` | string or null | optional. The route that lists the allowed values, or null.
- `filter_keys` | array of SchemaFilterKey | required. The named filter keys a request may send.
  - `key` | string | required. The filter key name.
  - `type` | enum | required. The shape the key takes. The list is frozen. Values: `list`, `string`, `boolean`, `integer`, `month`.
  - `description` | string | required. One sentence about what the key matches.
  - `column` | string or null | optional. The column the key reads, or null for a derived key.
  - `excludes` | string or null | optional. The `exclude_*` twin of this key, or null when it has none.
  - `values_route` | string or null | optional. The route that lists the allowed values, or null.
  - `aliases` | array of string | optional. Input spellings that normalize to this key or its values.
- `notes` | array of string | optional. Stated limits of the filter language, for example that past employers are not in the data.

## Failures

| Status | Meaning |
| --- | --- |
| `401` | The credential is missing, unknown or revoked. |
| `429` | The key passed 300 requests a minute or 2 concurrent requests. |

## Example

```bash
curl -sS "https://api.leadmcp.ai/v1/companies/schema" \
  -H "Authorization: Bearer lm_live_YOUR_API_KEY" \
  -H "LeadMCP-Version: 2026-09-19"
```

Response `200`:

```json
{
  "ok": true,
  "request_id": "req_01JBQ2W8K9V6M3T0X5Y7Z4A1BC",
  "release": "b_2026_09_15",
  "data": {
    "columns": [
      {
        "name": "headcount_band",
        "type": "string",
        "description": "The company employee band.",
        "nullable": true,
        "closed_list": true,
        "values_route": "/companies/schema/headcount_band/values"
      }
    ],
    "filter_keys": [
      {
        "key": "company_size",
        "type": "list",
        "description": "Matches the 'headcount_band' column.",
        "column": "headcount_band",
        "excludes": null,
        "values_route": "/companies/schema/headcount_band/values"
      }
    ],
    "notes": [
      "To find the people at these companies, send their ids to POST /contacts/search in the company_ids filter key."
    ]
  },
  "quota": {
    "plan": "free",
    "contact_credits_used": 50,
    "month_remaining": 950,
    "today_remaining": 950,
    "binding": "month",
    "resets_at": "9999-12-31T23:59:59.000Z"
  },
  "warnings": []
}
```