Set Contact Custom Field

Set a custom field value for a contact. Creates or updates the value (upsert behavior).

Request

PUT /contacts/{contactUuid}/custom-fields/{fieldUuid}

Path Parameters

Parameter	Type	Description
contactUuid	string	Contact's UUID
fieldUuid	string	Custom field's UUID

Request Body

Parameter	Type	Required	Description
value	mixed	Yes	The value to set (type depends on field type)

Supported Field Types and Value Formats

Field Type	Expected Value	Examples
text	string or numeric (max 255 characters)	"Acme Inc", 123
number	numeric	42, 3.14, "100"
boolean	bool, string, or int	true, false, "yes", "no", 1, 0
date	date string	"2025-01-15", "15/01/2025"
datetime	datetime string (no Z/offset)	"2025-01-15T10:30:00", "2025-01-15 10:30:00"
select	string	Must match one of the predefined options
list	array of strings	["Webinar X", "Webinar Y"] — replaces the whole list

For a list field, value must be an array. Each element is a non-empty string up to 255 characters, max 100 elements; elements are trimmed and de-duplicated, order is preserved. Sending [] clears the list.

Supported Date Formats (for date fields)

A date value is stored as YYYY-MM-DD; any time component is dropped. Accepted input:

• ISO 8601: Y-m-d\TH:i:sP, Y-m-d\TH:i:s
• Standard: Y-m-d H:i:s, Y-m-d
• European: d/m/Y, d-m-Y, d.m.Y (with optional time)
• US: m/d/Y, m-d-Y (with optional time)

Supported DateTime Formats (for datetime fields)

A datetime value accepts only the following formats — no timezone offset or Z suffix:

• Y-m-d\TH:i:s — e.g. "2025-01-15T10:30:00"
• Y-m-d H:i:s — e.g. "2025-01-15 10:30:00"
• Y-m-d\TH:i — e.g. "2025-01-15T10:30"
• Y-m-d H:i — e.g. "2025-01-15 10:30"

When read back via Get Contact Custom Fields, a datetime value is returned in ISO 8601 UTC form with a Z suffix (e.g. "2025-01-15T10:30:00Z").

Example Request (text)

curl -X PUT "https://email.easy.tools/api/v1/contacts/b8e4d6a1-3c52-4f7e-9a08-6d1b2c3e4f5a/custom-fields/f4e3d2c1-b0a9-4876-9543-21fedcba0987" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "value": "Acme Inc"
  }'

Example Request (boolean)

curl -X PUT "https://email.easy.tools/api/v1/contacts/b8e4d6a1-3c52-4f7e-9a08-6d1b2c3e4f5a/custom-fields/1f2e3d4c-5b6a-4798-8c0d-1e2f3a4b5c6d" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "value": true
  }'

Example Request (date)

curl -X PUT "https://email.easy.tools/api/v1/contacts/b8e4d6a1-3c52-4f7e-9a08-6d1b2c3e4f5a/custom-fields/9a8b7c6d-5e4f-4302-a1b0-9c8d7e6f5a4b" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "value": "2025-01-15"
  }'

Example Request (list)

curl -X PUT "https://email.easy.tools/api/v1/contacts/b8e4d6a1-3c52-4f7e-9a08-6d1b2c3e4f5a/custom-fields/3b4c5d6e-7f80-4912-a3b4-c5d6e7f8a90b" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "value": ["Webinar X", "Webinar Y"]
  }'

Response

Success Response (200 OK)

{
  "data": {
    "field_key": "company",
    "value": "Acme Inc"
  }
}

For a list field, value is the normalized array that was stored:

{
  "data": {
    "field_key": "events-attended",
    "value": ["Webinar X", "Webinar Y"]
  }
}

Response Fields

Field	Type	Description
field_key	string	The field's unique key
value	mixed	The stored value

Error Responses

Not Found Error (404) - Contact

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Contact not found"
  }
}

Not Found Error (404) - Field

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Custom field not found"
  }
}

The value-validation errors below return details as an empty array.

Validation Error (422 — Invalid value type)

The message names the field's type, e.g. number, boolean, date, datetime, text, select, or list.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid value for field type: number",
    "details": []
  }
}

Validation Error (422 — Invalid select option)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Value 'invalid' is not a valid option. Allowed options: free, pro, enterprise",
    "details": []
  }
}

Validation Error (422 — Value too long)

Returned when a text value, or any list element, exceeds the maximum length of 255 characters.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Value exceeds the maximum length of 255 characters",
    "details": []
  }
}

Validation Error (422 — Too many list elements)

Returned when a list value contains more than 100 elements.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "List exceeds the maximum of 100 elements",
    "details": []
  }
}