---
title: "Define a custom contact field"
method: POST
path: "/api/v1/sites/{id}/contacts/fields"
tags: ["CRM"]
---

# Define a custom contact field

`POST /api/v1/sites/{id}/contacts/fields`

## Request

- Base URL: `https://app.mondovo.com`
- URL: `https://app.mondovo.com/api/v1/sites/{id}/contacts/fields`
- Auth: HTTP bearer

Declares a custom attribute so it becomes a labelled, filterable field rather than a raw key. Use it for a specific label or a non-text type — a plain text field is created automatically by the import for any new key it sees. Defining a field never changes existing contact values. Requires scope `crm:write`.

## Request body

- object
  - `field_key` string, required: Identifier-shaped: starts with a letter or underscore, then letters, digits or underscores.
  - `label` string, required
  - `field_type` 'text' | 'number' | 'select' | 'boolean' | 'date'
  - `options` string[]: Only for `select`.

## Response `201`

Field defined.

## Other responses

- `400`: `invalid_field` — bad key syntax, or the field is already defined.
- `401`: Authentication failed. Error codes: `invalid_api_key` (missing/unknown key), `key_revoked`, `key_expired`.
- `403`: Authenticated but not allowed. Error codes: `addon_required`, `missing_scope`, and `demo_site_readonly` (contacts on a demo site cannot be modified).
- `404`: `site_not_found`.
- `429`: Rate limit exceeded (`rate_limit_exceeded`). The body includes `retry_after_seconds`, `limit`, and `window` ("minute" or "hour"); a `Retry-After` header is also set.

---

[API](https://skmtc.dev/mondovo/apis/mondovo-public-api.md) · [All operations](https://skmtc.dev/mondovo/apis/mondovo-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mondovo/apis/mondovo-public-api/revisions/1baa3e2865ba?raw)