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

# Update a contact

> Update an existing contact in your Peoplewisher account.

<RequestExample>
  ```bash cURL theme={null}
  curl --request PATCH \
    --url 'https://api.peoplewisher.com/v1/contacts/4812' \
    --header 'Authorization: Bearer YOUR_API_KEY' \
    --header 'Content-Type: application/json' \
    --data '{
      "first_name": "Ada",
      "last_name": "Okafor",
      "email": "ada.okafor@example.com",
      "birthday": "1994-10-13",
      "timezone": "Africa/Lagos",
      "group_id": 24
    }' 
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "success": true,
    "data": {
      "contact_id": 4812,
      "first_name": "Ada",
      "last_name": "Okafor",
      "email": "ada.okafor@example.com",
      "phone": "+2348012345678",
      "whatsapp_phone": "+2348012345678",
      "birthday": "1994-10-13",
      "timezone": "Africa/Lagos",
      "group_id": 24,
      "group_name": "Customers",
      "source": "api"
    }
  }
  ```
</ResponseExample>

## How it works

Use the Peoplewisher `contact_id` returned when the contact is created. Updating `group_id` moves the contact to the selected Celebration Group. If the birthday changes, Peoplewisher updates the relevant birthday processing state.

## Authentication

Include your Peoplewisher API key as a Bearer token on every request:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

Your API key is available in **Peoplewisher → Settings → API**. Keep it private and never expose it in browser-side code or public repositories.


## OpenAPI

````yaml openapi.yaml PATCH /contacts/{contact_id}
openapi: 3.0.3
info:
  title: Peoplewisher API
  version: 1.0.0
  description: |
    The Peoplewisher API lets an application synchronize contacts and place
    those contacts into Peoplewisher Celebration Groups. Peoplewisher then
    runs the celebration workflows configured for those groups in the
    Peoplewisher application.

    The public API is intentionally focused: applications provide people data
    and group membership. Templates, channels, schedules, celebration
    settings, and workflow behavior are managed in the Peoplewisher UI.
servers:
  - url: https://api.peoplewisher.com/v1
    description: Peoplewisher API
security:
  - bearerAuth: []
tags:
  - name: Contacts
    description: Manage the people whose celebrations Peoplewisher handles.
  - name: Celebration Groups
    description: >-
      Manage the Peoplewisher groups that determine which celebration workflow
      applies to a contact.
paths:
  /contacts/{contact_id}:
    patch:
      tags:
        - Contacts
      summary: Update a contact
      description: |
        Updates an existing contact belonging to the authenticated account.

        If the birthday changes, Peoplewisher resets the relevant birthday
        delivery pickup state so the updated date can be processed correctly.
      operationId: updateContact
      parameters:
        - $ref: '#/components/parameters/ContactId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactUpdate'
            example:
              first_name: Ada
              last_name: Okafor
              email: ada.okafor@example.com
              birthday: '1994-10-13'
              timezone: Africa/Lagos
              group_id: 24
      responses:
        '200':
          description: Contact updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContactMutationResponse'
              example:
                success: true
                data:
                  contact_id: 4812
                  first_name: Ada
                  last_name: Okafor
                  email: ada.okafor@example.com
                  phone: '+2348012345678'
                  whatsapp_phone: '+2348012345678'
                  birthday: '1994-10-13'
                  timezone: Africa/Lagos
                  group_id: 24
                  group_name: Customers
                  source: api
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/ValidationError'
        '429':
          $ref: '#/components/responses/RateLimited'
      x-codeSamples:
        - lang: curl
          source: |-
            curl --request PATCH \
              --url 'https://api.peoplewisher.com/v1/contacts/4812' \
              --header 'Authorization: Bearer YOUR_API_KEY' \
              --header 'Content-Type: application/json' \
              --data '{
                "first_name": "Ada",
                "last_name": "Okafor",
                "email": "ada.okafor@example.com",
                "birthday": "1994-10-13",
                "timezone": "Africa/Lagos",
                "group_id": 24
              }' 
components:
  parameters:
    ContactId:
      name: contact_id
      in: path
      required: true
      description: Peoplewisher contact ID.
      schema:
        type: integer
        minimum: 1
  schemas:
    ContactUpdate:
      type: object
      properties:
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
        phone:
          type: string
          description: Primary phone number.
        whatsapp_phone:
          type: string
        birthday:
          type: string
          format: date
          description: >-
            Birthday in YYYY-MM-DD format. The year may be omitted when only
            month/day are known.
        timezone:
          type: string
          example: Africa/Lagos
        gender:
          type: string
        location:
          type: string
        language:
          type: string
        company:
          type: string
        job_title:
          type: string
        salutation:
          type: string
        relationship_status:
          type: string
        guardian_contact_id:
          type: integer
        profile_image:
          type: string
          description: URL or PeopleWisher-supported profile image reference.
        status:
          type: string
          default: '1'
        group_id:
          type: integer
          minimum: 1
        custom_fields:
          type: object
          additionalProperties: true
    ContactMutationResponse:
      type: object
      properties:
        success:
          type: boolean
        data:
          $ref: '#/components/schemas/Contact'
    Contact:
      type: object
      properties:
        contact_id:
          type: integer
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
          nullable: true
        phone:
          type: string
          nullable: true
        whatsapp_phone:
          type: string
          nullable: true
        profile_image:
          type: string
          nullable: true
        contact_status:
          type: string
        birthday_month:
          type: integer
          nullable: true
        birthday_day:
          type: integer
          nullable: true
        birthday_year:
          type: integer
          nullable: true
        gender:
          type: string
          nullable: true
        location:
          type: string
          nullable: true
        timezone:
          type: string
          nullable: true
        language:
          type: string
          nullable: true
        company:
          type: string
          nullable: true
        job_title:
          type: string
          nullable: true
        salutation:
          type: string
          nullable: true
        relationship_status:
          type: string
          nullable: true
        group_id:
          type: integer
          nullable: true
        group_name:
          type: string
          nullable: true
        guardian_contact_id:
          type: integer
          nullable: true
        source:
          type: string
        date_created:
          type: string
        date_updated:
          type: string
          nullable: true
    ErrorResponse:
      type: object
      required:
        - success
        - error
        - message
      properties:
        success:
          type: boolean
        error:
          type: string
        message:
          type: string
        request_id:
          type: string
          nullable: true
  responses:
    InvalidRequest:
      description: The request is malformed or required data is missing.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: invalid_request
            message: A valid group_id is required.
    NotFound:
      description: The requested resource does not exist in the authenticated account.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: not_found
            message: Contact not found.
    ValidationError:
      description: Request validation failed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: validation_error
            message: Please provide a valid email address.
    RateLimited:
      description: The API request was rate limited.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            error: rate_limited
            message: Too many requests. Please retry later.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: |
        Use the API key generated in Peoplewisher Settings as a Bearer token.

````