Add List Item

Add a single element to a contact's list custom field. This is the natural fit for event-driven updates — e.g. a webhook that fires when a contact attends a meeting and appends one value.

The operation is idempotent: adding an element that is already present is a no-op. It is also atomic — concurrent adds/removes will not lose updates.

This endpoint is only valid for fields of type list.

Request

POST /contacts/{contactUuid}/custom-fields/{fieldUuid}/items

Path Parameters

Parameter	Type	Description
contactUuid	string	Contact's UUID
fieldUuid	string	Custom field's UUID (must be a list field)

Request Body

Parameter	Type	Required	Description
value	string	Yes	The single element to add. Non-empty, max 255 characters. Trimmed before storing.

Example Request

curl -X POST "https://email.easy.tools/api/v1/contacts/contact-uuid-123/custom-fields/field-uuid-345/items" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "value": "Webinar X"
  }'

Response

Success Response (200 OK)

Returns the full resulting list after the add.

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

Response Fields

Field	Type	Description
field_key	string	The field's unique key
value	array of strings	The full list after the element was added

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) - Not a list field

Returned when the target field is not of type list.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Item operations are only supported for list type fields",
    "details": {}
  }
}

Validation Error (422) - Invalid value

Returned when value is missing, empty, or not a string.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid value for list item",
    "details": {}
  }
}

Validation Error (422) - Value too long

Returned when the 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) - List full

Returned when adding the element would exceed the maximum of 100 elements.

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