Update Contact

Partially update a contact. Only provided fields will be updated.

Request

PATCH /contacts/{uuid}

Path Parameters

Parameter	Type	Description
uuid	string	Contact's UUID

Request Body

All fields are optional. Only include fields you want to update.

Parameter	Type	Description
first_name	string|null	Contact's first name (max 255 characters). Send null or empty string to clear.
last_name	string|null	Contact's last name (max 255 characters). Send null or empty string to clear.
phone	string|null	Contact's phone number (max 32 characters). Send null or empty string to clear.
external_id	string|null	External identifier (max 255 characters). Send null or empty string to clear.
language	string|null	ISO 639-1 language code (2 characters). Send null or empty string to clear.
country_code	string|null	ISO 3166-1 alpha-2 country code (2 characters). Send null or empty string to clear.
custom_fields	array	Array of custom field values to set (see Custom Fields section below)

Note: The email field cannot be updated (it is an immutable identifier).

Note: For contacts originally created by Easycart integration, first_name and last_name updates are silently ignored to preserve data integrity.

Example Request

curl -X PATCH "https://email.easy.tools/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "first_name": "Jane",
    "language": "pl"
  }'

Custom Fields

You can update custom field values by including the custom_fields array in your request.

Custom Field Object

Field	Type	Required	Description
field_key	string	Yes	The unique key of the custom field
value	mixed	Yes	The value to set (type depends on field type). Send null or "" to delete.

Supported Field Types and Value Formats

Field Type	Expected Value	Example
text	string or numeric (max 255 characters)	"Acme Inc", 123
number	numeric	42, 3.14, "100"
boolean	bool, or string/int representation	true, false, "yes", "no", 1, 0
date	date string	"2025-01-15", "15/01/2025", "01-15-2025"
datetime	datetime string	"2025-01-15T10:30:00Z", "2025-01-15 10:30:00"
select	string (must match predefined option)	"enterprise"
list	array of strings (replaces whole list; max 100 elements, each ≤255 chars)	["Webinar X", "Webinar Y"]

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 with Custom Fields

curl -X PATCH "https://email.easy.tools/api/v1/contacts/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "first_name": "Jane",
    "custom_fields": [
      {"field_key": "company", "value": "Acme Inc"},
      {"field_key": "plan", "value": "enterprise"},
      {"field_key": "is_vip", "value": true},
      {"field_key": "signup_date", "value": "2025-01-15"},
      {"field_key": "events-attended", "value": ["Webinar X", "Webinar Y"]},
      {"field_key": "old_field", "value": null}
    ]
  }'

Deleting Custom Field Values

To remove a custom field value from a contact, send null or an empty string "" as the value:

{
  "custom_fields": [
    {"field_key": "company", "value": null}
  ]
}

Response

Success Response (200 OK)

{
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "email": "john@example.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+48123456789",
    "external_id": "customer_123",
    "language": "pl",
    "country_code": "US",
    "lists": [
      {
        "uuid": "list-uuid-1",
        "name": "Newsletter"
      }
    ],
    "custom_fields": [
      {
        "field_key": "company",
        "value": "Acme Inc"
      }
    ],
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-16T14:00:00Z"
  }
}

Error Responses

Not Found Error (404)

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Contact with uuid '550e8400-e29b-41d4-a716-446655440000' not found"
  }
}

Custom Field Validation Error (422)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Custom field 'invalid_key' not found",
    "details": {
      "custom_fields": ["Custom field 'invalid_key' not found"]
    }
  }
}

Invalid Select Option Error (422)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid value for custom field 'plan'. Value 'invalid_option' is not a valid option. Valid options are: free, pro, enterprise",
    "details": {
      "custom_fields": ["Invalid value for custom field 'plan'. Value 'invalid_option' is not a valid option. Valid options are: free, pro, enterprise"]
    }
  }
}

Value Too Long Error (422)

Returned when a text custom field value exceeds the maximum length of 255 characters.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Custom field 'company' value exceeds the maximum length of 255 characters",
    "details": {
      "custom_fields": ["Custom field 'company' value exceeds the maximum length of 255 characters"]
    }
  }
}