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). Must be unique within your account. 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.
timezone_uuid	string|null	UUID of the timezone to assign to the contact, from List Timezones. Send null to clear. An unknown UUID returns 404.
contact_lists	array of strings	UUIDs of lists to add the contact to. Additive — listed lists are added; existing memberships are never removed by this endpoint. Each UUID must reference an existing list.
custom_fields	array	Array of custom field values to set (see Custom Fields section below)

Note: The email field cannot be updated.

Note: For contacts managed by the easycart integration, first_name and last_name updates are silently ignored. Other fields, including phone, external_id, language, country_code, and custom_fields, are still applied.

Note: contact_lists never removes memberships — to take a contact off a list, use Remove Contact from List. A contact that previously unsubscribed from a listed list is not re-added, and an unknown list UUID makes the whole request fail with 404.

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 (key must be present)	The value to set (type depends on field type). The value key must be present on each entry; send null or "" to delete the value.

Supported Field Types and Value Formats

Custom field values accept the same types and formats as on Create Contact — see Supported Field Types and Value Formats.

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": "a3f1c5d2-7e84-4b9f-8c63-1d0e2f3a4b5c",
        "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"
  }
}

Not Found Error (404) — Timezone

Returned when timezone_uuid does not match a timezone from List Timezones. The contact is not updated in this case.

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

Duplicate Contact Error (409 Conflict)

Returned when the external_id you sent is already used by another contact. Each external_id must be unique within your account. The contact is not updated in this case.

{
  "error": {
    "code": "DUPLICATE_RESOURCE",
    "message": "Contact with external id 'customer_123' already exists"
  }
}

Custom Field Validation Error (422 Unprocessable Entity)

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

Invalid Select Option Error (422)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Custom field validation failed",
    "details": {
      "custom_fields": ["Custom field 'plan' value 'invalid_option' is not a valid option. Allowed options: 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 validation failed",
    "details": {
      "custom_fields": ["Custom field 'company' value exceeds the maximum length of 255 characters"]
    }
  }
}