---
title: "Create a contact field"
method: POST
path: "/v1/sites/{site_id}/contact-fields"
tags: ["Contact fields"]
---

# Create a contact field

`POST /v1/sites/{site_id}/contact-fields`

## Request

- Base URL: `https://api.getsitecontrol.com`
- URL: `https://api.getsitecontrol.com/v1/sites/{site_id}/contact-fields`
- Auth: HTTP bearer

Creates a custom contact field and returns it. Its id is made from the name
in camelCase, with a digit appended when that id is taken; contacts take
values for it in `fields` under that id.

The name needs at least three latin letters or digits, and the id made from
it must fit 100 characters. It must differ, without case, from the names of
the other fields of the site, system fields such as "Email" or "First name"
included.

A field created with the name of a deleted one gets the same id and shows
the values contacts kept for it.

## Path parameters

- `site_id` integer, required

## Headers

- `Idempotency-Key` string: Makes a retry of a POST safe: a repeat with the same key, body and GSC-Version returns the stored response with `Idempotency-Replayed: true` instead of running again. The key protects against repeated execution while the key store works. Saving the change and storing the response under the key are not atomic: if the process or the key store fails between them, the change is kept, the key is released after 15 minutes and a retry runs the request again. After a timeout or a 5xx, read the resource to check the result before retrying. 5xx and 429 responses and responses over 256 KB are not stored, so a repeat runs the request again. A key is kept for 24 hours. The same key with another body or version is 422; a repeat while the first request runs is 409.

## Request body

- ContactFieldCreate
  - `name` string, required: Display name; the id is made from it
  - `type` 'text' | 'number' | 'datetime': `text`: a string; `number`: a number, decimals allowed; `datetime`: a moment, ISO 8601 in UTC.

## Response `201`

Successful Response

- ContactField
  - `id` string, required: Derived from the name on creation; kept on rename
  - `name` string, required: Display name
  - `type` 'text' | 'integer' | 'number' | 'datetime' | 'date' | 'boolean' | 'other', required: `text`: a string; `integer`: a whole number; `number`: a number, decimals allowed; `datetime`: a moment, ISO 8601 in UTC; `date`: a day, YYYY-MM-DD; `boolean`: true or false; `other`: a field kept from older versions of the admin, read-only on contacts.
  - `created_at` string, date-time, nullable: Null for fields created before the date was recorded

## Other responses

- `400`: Unsupported GSC-Version
- `401`: Missing or invalid API key or access token
- `403`: Access denied
- `404`: Not found
- `409`: `field_name_taken`: another field of the site has this name, compared without case. `idempotency_in_progress`: a repeat of a request still running
- `413`: Request body too large
- `422`: `field_name_invalid`: the name has fewer than three latin letters or digits, or the id made from it is too long. `validation_failed`: the body is invalid. `idempotency_key_reused`: the `Idempotency-Key` was sent before with another body or version
- `429`: Rate limited
- `503`: Temporarily unavailable; retry later

---

[API](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api.md) - [All operations](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api/revisions/084fcad80e75?raw)