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

# Upsert Contact

> Update or create a contact in your phone address book and WhatsApp.

Update a contact in your phone address book using a phone number.

This endpoint allows you to:

* Create a new contact in your phone's address book
* Update an existing contact's information
* Sync contact details to WhatsApp using the contact's phone number

<Info>
  This endpoint is intended for phone-number-based contact management and address book synchronization.
</Info>

## Use Cases

### Contact Management

Automatically create or update contacts when new users register in your system.

### CRM Synchronization

Keep your WhatsApp contacts in sync with your CRM database.

### Bulk Contact Import

Import and update multiple contacts from external sources.

## Request Parameters

### chat\_id

Use the contact's phone number only.

* **Phone number**: `12132132130`

<Info>
  Send the number with country code and without spaces or the `+` sign. Example: `12132132130`
</Info>

<Danger>
  Do not use an `@lid` identifier with this endpoint.

  If the same person is handled once by phone number and again by LID, WhatsApp may treat them as two separate contacts. For upsert operations, always use the phone number only.
</Danger>

### first\_name

The contact's first name (required).

### last\_name

The contact's last name (optional).

## Response Examples

### Successful Response

When the contact is upserted successfully:

```json theme={null}
{
  "message": "Contact upserted successfully.",
  "data": {
    "success": true
  }
}
```

<Warning>
  **Phone Address Book Update Note**

  If you have multiple WhatsApp apps installed on your phone, the API might only work with one account.
  You may need to make a few API requests with the same parameters and wait a few seconds between requests to update your phone address book.
</Warning>

## Best Practices

### Multiple Requests

If the contact doesn't appear in your address book immediately, try making 2-3 requests with a few seconds delay between them.

### Verification

After upserting a contact, you can use the **Get Contact** endpoint to verify the update was successful.

### Error Handling

Always implement proper error handling to catch validation errors or API failures.


## OpenAPI

````yaml v2/api-reference/whatsapp/whatsapp-collection.json POST /{instance}/contacts/upsert
openapi: 3.1.0
info:
  version: v2.0
  title: Hypersender WhatsApp API Docs
  description: >

    The Hypersender WhatsApp API is a powerful api to send and recieve messages
    using your own whatsapp number.

    Without the high costs of Meta's Whatsapp business API.


    In this Docs you'll learn how to use and integrate Hypersnder Whatsapp API
    into your existing system/service or application using simple API endpoints.


    ## What's New in V2?


    **Queued Responses:** All requests in V2 are now queued for improved
    reliability and performance. When you make a request, you'll receive an
    immediate response with a `queued_request_uuid` that you can use to check
    the status of your request.


    **Example Response:**

    ```json

    {
        "queued": true,
        "message": "Processing your request...",
        "queued_request_uuid": "a0816120-7e37-4e8b-8cf3-92deb2cdc133",
        "queued_request_link": "https://app.hypersender.com/api/whatsapp/v2/{instance}/queued-requests/{queued_request_uuid}"
    }

    ```


    Use the `queued_request_link` or the **Get Queued Request** endpoint to
    check the actual message response once it's processed.


    **What you can Do?**


    - Send Text and basic Url messages.

    - Send Media through Link or uploaded file.

    - Send Audio through Link or uploaded file.

    - Send Contact Card

    - Send Location

    - Send Poll votes


    **You can also**


    - React to a message

    - Forward messages to other chats

    - Acknowledge messages (mark as read)

    - Star and unstar messages



    <hr />


    **Quick Demo**

      **Learn how to use Hypersender whatsapp API to send a message using Postman:**
      [Demo Link](https://app.hypersender.com/send-whatsapp-message-in-postman) **to easily interact with our API.**

    <hr />


    **postman collection**


    You can download our [Postman
    Collection](https://docs.hypersender.com/whatsapp-postman-collection.json)
    to easily interact with our API.


    ## Servers (Endpoints)


    - Production (activated):
    [https://app.hypersender.com/api/whatsapp/v2](https://app.hypersender.com/api/whatsapp/v2)
servers:
  - url: https://app.hypersender.com/api/whatsapp/v2
    description: Production
security:
  - Authorization: []
paths:
  /{instance}/contacts/upsert:
    post:
      tags:
        - Contacts
      summary: Upsert contact
      description: Update or create a contact in your phone address book and WhatsApp
      parameters:
        - name: Accept
          in: header
          description: application/json
          schema:
            type: string
            example: application/json
        - name: Content-Type
          in: header
          description: application/json
          schema:
            type: string
            example: application/json
        - name: instance
          in: path
          description: Instance UUID copied from hypersender dashboard
          required: true
          schema:
            type: string
            example: '{{ instance_id }}'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertContactRequest'
      responses:
        '200':
          description: Contact upserted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Contact upserted successfully.
                  data:
                    type: object
                    properties:
                      success:
                        type: boolean
                        example: true
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
      security:
        - Authorization: []
components:
  schemas:
    UpsertContactRequest:
      type: object
      properties:
        chat_id:
          type: string
          description: Phone number (123123123) or chat ID (123123@c.us or 123123@lid)
          example: 1234567890@c.us
        first_name:
          type: string
          description: The contact's first name
          example: John
        last_name:
          type: string
          description: The contact's last name
          example: Doe
      required:
        - chat_id
        - first_name
    NotFoundError:
      type: object
      title: NotFoundError
      example:
        message: Resource not found.
      properties:
        message:
          type: string
      x-examples:
        Example 1:
          message: Resource not found.
      x-stoplight:
        id: ar3vz55asbxme
    ValidationError:
      type: object
      title: ValidationError
      properties:
        message:
          type: string
        errors:
          type: object
          description: Invalid or missing feilds will be shown here
        statusCode:
          type: number
      example:
        message: The given data was invalid.
        errors: {}
        statusCode: 422
      required:
        - errors
        - statusCode
      x-examples:
        Multiple fields Error:
          message: The given data was invalid.
          errors:
            messages:
              - The number you want to send the message to is not on whatsapp.
            jid: 20121323124131@s.whatsapp.net
            exists: false
          statusCode: 422
        'Single Field error ':
          message: The given data was invalid.
          errors:
            messages:
              - textMessage.text should not be empty
          statusCode: 422
      x-stoplight:
        id: 90x3wfxw7gqcb
    ServerError:
      type: object
      title: ServerError
      properties:
        message:
          type: string
      example:
        message: Internal Server Error
      x-stoplight:
        id: 2fhq2gihsfreh
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer

````