Update Contact

Update an existing contact information

PUT /api/v1/contacts

cURL

update_by_id

curl --request PUT \
  --url https://chat.trysetter.com/api/v1/contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "id": 123,
  "firstName": "John",
  "lastName": "Smith",
  "email": "[e-mail]",
  "defaultTimeZone": "America/New_York",
  "metadata": {
    "source": "updated_via_api",
    "last_interaction": "2024-01-15"
  }
}
'

200

Example

{
  "data": {
    "id": 123,
    "createdAt": "2024-01-01T10:00:00Z",
    "updatedAt": "2024-01-15T14:30:00Z",
    "firstName": "John",
    "lastName": "Smith",
    "fullName": "John Smith",
    "phoneNumber": "1234567890",
    "waId": "1234567890",
    "smsPhoneNumber": "1234567890",
    "email": "[e-mail]",
    "defaultTimeZone": "America/New_York",
    "metadata": {
      "source": "updated_via_api",
      "last_interaction": "2024-01-15"
    }
  }
}

Overview

This endpoint allows you to update an existing contact’s information in your Setter AI account. You can update contact details like name, email, phone number, timezone, and custom metadata fields.

Contact Identification: You must provide at least one identifier (ID, WhatsApp ID, or SMS phone number) to locate the contact.

Contact Identification

You can identify a contact using any of these methods:

By Contact ID

Use the internal contact ID for direct lookup:

{
  "id": 123,
  "firstName": "John"
}

By WhatsApp ID

Use the WhatsApp ID for contacts from WhatsApp integrations:

{
  "waId": "1234567890",
  "email": "[e-mail]"
}

By SMS Phone Number

Use the SMS phone number for contacts from SMS integrations:

{
  "smsPhoneNumber": "1234567890",
  "fullName": "John Doe"
}

Updatable Fields

All contact fields are optional in the update request. Only provided fields will be updated:

• firstName - Contact’s first name
• lastName - Contact’s last name
• fullName - Contact’s full name
• phoneNumber - Contact’s phone number
• email - Contact’s email address (must be valid format)
• defaultTimeZone - Contact’s default timezone (IANA format)
• metadata - Custom key-value pairs for additional contact data

Important Notes

• Authentication: All requests require a Bearer token in the Authorization header
• Unique Contact: If multiple contacts match the identifier, the operation fails with a 409 error
• Access Control: Only contacts that your organization has access to can be updated
• Validation: Email addresses are validated for proper format
• Metadata: The metadata field supports custom key-value pairs for storing additional contact information

Error Handling

The endpoint provides specific error responses for different scenarios:

• 400: Missing identifier or invalid field format
• 404: No contacts found with the provided identifier
• 409: Multiple contacts matched the identifier
• 401/403: Authentication or authorization errors

Getting Your API Key

API keys can be generated from your Setter AI dashboard under Settings > API Keys. Keep your API key secure and never expose it in client-side code.

Example Usage

Update Contact Name and Email

curl -X PUT https://chat.trysetter.com/api/v1/contacts \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 123,
    "firstName": "John",
    "lastName": "Smith", 
    "email": "[e-mail]"
  }'

Update Contact Metadata

curl -X PUT https://chat.trysetter.com/api/v1/contacts \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "waId": "1234567890",
    "metadata": {
      "source": "updated_via_api",
      "campaign": "winter2024",
      "last_interaction": "2024-01-15"
    }
  }'

Authorizations

Authorization · string · header · required

Bearer token authentication using your API key

Body

application/json

id · integer

Contact ID for direct lookup

Example:

123

waId · string

WhatsApp ID for contact lookup

Example:

"1234567890"

smsPhoneNumber · string

SMS phone number for contact lookup

Example:

"1234567890"

firstName · string

Contact's first name

Example:

"John"

lastName · string

Contact's last name

Example:

"Doe"

fullName · string

Contact's full name

Example:

"John Doe"

phoneNumber · string

Contact's phone number

Example:

"1234567890"

email · string<email>

Contact's email address

Example:

"[e-mail]"

defaultTimeZone · string

Contact's default timezone

Example:

"America/New_York"

metadata · object

Custom key-value pairs to store with the contact

Show child attributes

Example:

{
  "source": "website",
  "campaign": "summer2024"
}

Response

200

application/json

Contact updated successfully

data · object

Show child attributes

message · string

Status message

Example:

"Contact updated successfully"