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)

Expected Value Formats by Field Type

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	"2025-01-15T10:30:00Z", "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/DateTime Formats

• 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)

Example Request (text)

curl -X PUT "https://email.easy.tools/api/v1/contacts/contact-uuid-123/custom-fields/field-uuid-456" \
  -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/contact-uuid-123/custom-fields/field-uuid-789" \
  -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/contact-uuid-123/custom-fields/field-uuid-012" \
  -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/contact-uuid-123/custom-fields/field-uuid-345" \
  -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"
  }
}

Validation Error (422) - Invalid value type

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

Validation Error (422) - Invalid select option

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid option 'invalid' for select field. Valid 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": {}
  }
}