PUT
/
api
/
v1
/
contacts
/
{contact_id}
/
update

​
Update Contact

Update an existing contact with the specified information.

​
Endpoint

PUT /api/v1/contacts/{contact_id}/update
PATCH /api/v1/contacts/{contact_id}/update

Use PUT for a full update (replacing all fields) or PATCH for a partial update (only updating specified fields).

​
Authentication

This endpoint requires an API key with the can_read_contacts permission.

​
Path Parameters

ParameterTypeRequiredDescription
contact_idintegerYesThe ID of the contact to update

​
Request Body

The request body can include any of the fields available when creating a contact. Only the fields you include will be updated when using PATCH.

ParameterTypeRequiredDescription
first_namestringNoFirst name of the contact
last_namestringNoLast name of the contact
emailstringNoEmail address of the contact
companystringNoCompany or organization name
websitestringNoCompany or personal website URL
addressstringNoStreet address
citystringNoCity
statestringNoState or province
zip_codestringNoPostal or ZIP code
countrystringNoCountry
statusstringNoContact status
stagestringNoContact stage
team_idintegerNoID of the team to assign the contact to
tagsarrayNoArray of tag names (replaces existing tags)
phone_numbersarrayNoArray of phone number objects
custom_contextobjectNoCustom fields and data
industry_contextobjectNoIndustry-specific information

​
Phone Number Object for Updates

When updating phone numbers, you can include the id to update existing numbers:

ParameterTypeRequiredDescription
idintegerNoID of an existing phone number (for updates)
phone_numberstringYesPhone number in E.164 format
phone_typestringNoType of phone (mobile, work, home, etc.)
primarybooleanNoWhether this is the primary phone number
do_not_callbooleanNoWhether this number is on the do not call list

​
Example Request Body (PATCH)

{
  "email": "[email protected]",
  "status": "contacted",
  "stage": "qualified_lead",
  "tags": ["Qualified", "High Priority"],
  "phone_numbers": [
    {
      "id": 456,
      "primary": false
    },
    {
      "phone_number": "+15553456789",
      "phone_type": "home",
      "primary": true
    }
  ],
  "custom_context": {
    "lead_source": "Referral",
    "budget": "$10,000-$20,000"
  }
}

​
Response

{
  "id": 123,
  "first_name": "John",
  "last_name": "Doe",
  "full_name": "John Doe",
  "email": "[email protected]",
  "message": "Contact updated successfully"
}

​
Error Codes

Status CodeError CodeDescription
400invalid_jsonInvalid JSON payload
400validation_errorValidation error with details
401authentication_requiredNo API key was provided
401invalid_keyThe API key is invalid or inactive
403permission_deniedThe API key doesn’t have the required permission
403team_access_deniedYou do not have access to this team
404not_foundContact not found or you do not have access
404team_not_foundTeam not found
500server_errorAn unexpected server error occurred

​
Example Request (PATCH)

curl -X PATCH 'https://api.klen.ai/api/v1/contacts/123/update' \
  -H 'Authorization: Bearer klen_abcdef123456789' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "contacted",
    "stage": "qualified_lead",
    "tags": ["Qualified", "High Priority"]
  }'

​
Example Response

{
  "id": 123,
  "first_name": "John",
  "last_name": "Doe",
  "full_name": "John Doe",
  "email": "[email protected]",
  "message": "Contact updated successfully"
}

​
Notes on Update Behavior

​
PUT vs PATCH

  • PUT requests replace the entire contact object. Any fields not included in the request will be set to their default values or null.
  • PATCH requests only update the fields included in the request. Existing fields not mentioned in the request remain unchanged.

​
Phone Numbers

  • When using PUT, all existing phone numbers will be deleted and replaced with those in the request.
  • When using PATCH:
    • Phone numbers with an id will be updated if they exist.
    • Phone numbers without an id will be added as new numbers.
    • Existing phone numbers not referenced in the request remain unchanged.

​
Tags

  • The tags array completely replaces the existing tags for both PUT and PATCH requests.

​
Custom and Industry Context

  • When using PUT, the entire context object is replaced.
  • When using PATCH, the context objects are merged with existing data, with new values overwriting old ones for the same keys.