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

# List columns

`GET /contacts/schema`

Returns every public column with its format, and every filter key with its type and its value route. Top-level job fields (title, company, company_domain, function, seniority, role_since) describe the main role. experience lists the person's current roles only, main role first; the source has no past roles. A housekeeping date (`last_updated`, `last_refreshed`) carries the month. A role start date (`role_since`) carries the day, because a job-change signal is only worth acting on when you know the day it happened. Free.

Returns every public column with its format, and every filter key with its type and its value route. Top-level job fields (title, company, company_domain, function, seniority, role_since) describe the main role. experience lists the person's current roles only, main role first; the source has no past roles. A housekeeping date (`last_updated`, `last_refreshed`) carries the month. A role start date (`role_since`) carries the day, because a job-change signal is only worth acting on when you know the day it happened. 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. |
| `503` | The data is unavailable for a short time. |

## Example

```bash
curl -sS "https://api.leadmcp.ai/v1/contacts/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": "work_email",
        "type": "string",
        "description": "The work email, lowercased.",
        "nullable": true,
        "closed_list": false,
        "values_route": null
      },
      {
        "name": "seniority",
        "type": "string",
        "description": "The seniority rung of the current role.",
        "nullable": true,
        "closed_list": true,
        "values_route": "/contacts/schema/seniority/values"
      }
    ],
    "filter_keys": [
      {
        "key": "seniority",
        "type": "list",
        "description": "Seniority rungs to include.",
        "column": "seniority",
        "excludes": "exclude_seniority",
        "values_route": "/contacts/schema/seniority/values",
        "aliases": [
          "Vice President"
        ]
      }
    ],
    "notes": [
      "Past employers are not in the data: experience lists current roles only."
    ]
  },
  "quota": {
    "plan": "free",
    "contact_credits_used": 50,
    "month_remaining": 950,
    "today_remaining": 950,
    "binding": "month",
    "resets_at": "9999-12-31T23:59:59.000Z"
  },
  "warnings": []
}
```