> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trysetter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Contact

> Update an existing contact information

## 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.

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

## Contact Identification

You can identify a contact using any of these methods:

### By Contact ID

Use the internal contact ID for direct lookup:

```json theme={null}
{
  "id": 123,
  "firstName": "John"
}
```

### By WhatsApp ID

Use the WhatsApp ID for contacts from WhatsApp integrations:

```json theme={null}
{
  "waId": "1234567890",
  "email": "john@example.com"
}
```

### By SMS Phone Number

Use the SMS phone number for contacts from SMS integrations:

```json theme={null}
{
  "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

```bash theme={null}
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": "john.smith@example.com"
  }'
```

### Update Contact Metadata

```bash theme={null}
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"
    }
  }'
```


## OpenAPI

````yaml PUT /api/v1/contacts
openapi: 3.0.3
info:
  title: Setter AI API
  description: API for Setter AI appointment booking assistant
  version: 1.0.0
  contact:
    email: support@trysetter.com
servers:
  - url: https://chat.trysetter.com
    description: Production server
security:
  - bearerAuth: []
paths:
  /api/v1/contacts:
    put:
      tags:
        - Contacts
      summary: Update Contact
      description: >-
        Update an existing contact's information. You can identify the contact
        using either ID, WhatsApp ID (waId), or SMS phone number
        (smsPhoneNumber). Only one identifier is required, but at least one must
        be provided.


        **Important Notes:**

        - If multiple contacts match the identifier, the operation will fail
        with a 409 error

        - If no contacts are found, the operation will return a 404 error

        - Only contacts that your organization has access to can be updated

        - All fields except the identifier are optional and will only be updated
        if provided
      operationId: updateContact
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateContactRequest'
            examples:
              update_by_id:
                summary: Update contact by ID
                value:
                  id: 123
                  firstName: John
                  lastName: Smith
                  email: john.smith@example.com
                  defaultTimeZone: America/New_York
                  metadata:
                    source: updated_via_api
                    last_interaction: '2024-01-15'
              update_by_whatsapp_id:
                summary: Update contact by WhatsApp ID
                value:
                  waId: '1234567890'
                  fullName: Jane Doe
                  email: jane.doe@example.com
                  defaultTimeZone: America/Los_Angeles
              update_by_sms_phone:
                summary: Update contact by SMS phone number
                value:
                  smsPhoneNumber: '1234567890'
                  firstName: Alice
                  lastName: Johnson
                  metadata:
                    source: sms_campaign
                    campaign_id: campaign_123
      responses:
        '200':
          description: Contact updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateContactResponse'
              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: john.smith@example.com
                  defaultTimeZone: America/New_York
                  metadata:
                    source: updated_via_api
                    last_interaction: '2024-01-15'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missing_identifier:
                  summary: Missing contact identifier
                  value:
                    message: Either id, waId or smsPhoneNumber is required
                invalid_email:
                  summary: Invalid email format
                  value:
                    message: Invalid email format
                no_fields:
                  summary: No updatable fields provided
                  value:
                    data: null
                    message: No updatable fields provided
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Unauthorized
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Not authorized
        '404':
          description: Contact not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: No accessible contacts found
        '409':
          description: Multiple contacts found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                message: Multiple contacts matched; no update performed
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Internal server error occurred
components:
  schemas:
    UpdateContactRequest:
      type: object
      properties:
        id:
          type: integer
          description: Contact ID for direct lookup
          example: 123
        waId:
          type: string
          description: WhatsApp ID for contact lookup
          example: '1234567890'
        smsPhoneNumber:
          type: string
          description: SMS phone number for contact lookup
          example: '1234567890'
        firstName:
          type: string
          description: Contact's first name
          example: John
        lastName:
          type: string
          description: Contact's last name
          example: Doe
        fullName:
          type: string
          description: Contact's full name
          example: John Doe
        phoneNumber:
          type: string
          description: Contact's phone number
          example: '1234567890'
        email:
          type: string
          format: email
          description: Contact's email address
          example: john@example.com
        defaultTimeZone:
          type: string
          description: Contact's default timezone
          example: America/New_York
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Custom key-value pairs to store with the contact
          example:
            source: website
            campaign: summer2024
    UpdateContactResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/Contact'
        message:
          type: string
          description: Status message
          example: Contact updated successfully
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: Error message
    Contact:
      type: object
      properties:
        id:
          type: integer
          description: Contact ID
          example: 123
        createdAt:
          type: string
          format: date-time
          description: Contact creation timestamp
        updatedAt:
          type: string
          format: date-time
          description: Contact last update timestamp
        firstName:
          type: string
          description: Contact's first name
          example: John
        lastName:
          type: string
          description: Contact's last name
          example: Doe
        fullName:
          type: string
          description: Contact's full name
          example: John Doe
        phoneNumber:
          type: string
          description: Contact's phone number
          example: '1234567890'
        waId:
          type: string
          description: WhatsApp ID
          example: '1234567890'
        smsPhoneNumber:
          type: string
          description: SMS phone number
          example: '1234567890'
        email:
          type: string
          format: email
          description: Contact's email address
          example: john@example.com
        defaultTimeZone:
          type: string
          description: Contact's default timezone
          example: America/New_York
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Custom key-value pairs stored with the contact
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using your API key

````