Create Custom Field

Create a new custom field definition.

Request

POST /custom-fields

Request Body

Parameter	Type	Required	Description
name	string	Yes	Display name for the field (max 255 characters)
field_key	string	No	Unique key for the field. If not provided, auto-generated from name. Must be lowercase letters, numbers, and hyphens only (e.g., "my-field-key")
type	string	Yes	Field type: text, number, date, datetime, boolean, select, list
options	array	Conditional	Required for select type. Array of string options. Must not be provided for list (which is free-form).

list type

A list field stores multiple free-form string values per contact (e.g. events a contact attended). It is free-form — do not send options. Values are managed via the Contact Custom Fields endpoints, including dedicated add/remove item endpoints.

Example Request (text field)

curl -X POST "https://email.easy.tools/api/v1/custom-fields" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Company",
    "type": "text"
  }'

Example Request (with custom field_key)

curl -X POST "https://email.easy.tools/api/v1/custom-fields" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Company Name",
    "field_key": "my-company-field",
    "type": "text"
  }'

Example Request (select field)

curl -X POST "https://email.easy.tools/api/v1/custom-fields" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Plan",
    "type": "select",
    "options": ["free", "pro", "enterprise"]
  }'

Example Request (list field)

curl -X POST "https://email.easy.tools/api/v1/custom-fields" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Events Attended",
    "type": "list"
  }'

Response

Success Response (201 Created)

{
  "data": {
    "uuid": "field-uuid-123",
    "field_key": "company",
    "name": "Company",
    "type": "text",
    "options": null,
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Success Response (select field)

{
  "data": {
    "uuid": "field-uuid-456",
    "field_key": "plan",
    "name": "Plan",
    "type": "select",
    "options": ["free", "pro", "enterprise"],
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Response Fields

Field	Type	Description
uuid	string	Unique identifier for the field
field_key	string	Unique key for the field
name	string	Display name
type	string	Field type
options	array|null	Options for select fields, null for other types
created_at	string	ISO 8601 timestamp (UTC)

Error Responses

Duplicate Field Key Error (409 Conflict)

{
  "error": {
    "code": "DUPLICATE_RESOURCE",
    "message": "Custom field with key 'company' already exists"
  }
}

Validation Error (422) - Select without options

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Select field type requires at least one option",
    "details": {
      "options": ["The options field is required when type is select."]
    }
  }
}

Validation Error (422) - List with options

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "List type fields do not accept options",
    "details": {}
  }
}

Validation Error (422) - Invalid field_key format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid",
    "details": {
      "field_key": ["The field key must only contain lowercase letters, numbers, and hyphens."]
    }
  }
}