---
agentTools:
  projectIndex: https://rampwin-api.readme.io/llms.txt
---

# Insert or Update Contact

Creates a new contact or updates an existing contact based on the phone number.

## Endpoint

`POST /api/contacts/insertOrUpdate`

**Base URL**

```bash URL
https://api.rampwin.com
```

***

## Description

This API performs an **upsert operation**:

* If the contact **does not exist** → creates a new contact
* If the contact **already exists** → updates the existing contact

This helps avoid duplicate contacts and simplifies contact management.

***

## Authentication

This API supports:

* API Key

***

## Headers

| Header       | Type   | Required | Description                      |
| ------------ | ------ | -------- | -------------------------------- |
| Content-Type | string | Yes      | application/json                 |
| x-api-key    | string | Yes      | Your Rampwin API key             |
| Cookie       | string | Yes      | AWS load balancer session cookie |

***

## Query Parameters

| Parameter   | Type   | Required | Description         |
| ----------- | ------ | -------- | ------------------- |
| channel\_id | string | Yes      | WhatsApp channel ID |

***

## Request Body

### Core Fields

| Field         | Type   | Required | Description                              |
| ------------- | ------ | -------- | ---------------------------------------- |
| phone\_number | string | Yes      | Contact phone number (with country code) |
| first\_name   | string | No       | First name                               |
| last\_name    | string | No       | Last name                                |
| email         | string | No       | Email address                            |

***

### Custom Attributes

You can also pass additional fields dynamically (same as Create Contact), such as:

* city
* state
* plan\_status
* tags
* timezone

***

## Example Request

```curl cURL
curl --location 'https://api.rampwin.com/api/contacts/insertOrUpdate?channel_id=YOUR_CHANNEL_ID' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Cookie: AWSALB=XXXXX; AWSALBCORS=XXXXX' \
--data-raw '{
  "phone_number": "+11234567890",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com"
}'
```

***

## Response

### Success (200)

```json JSON
{
  "success": true,
  "message": "Contact inserted or updated successfully",
  "data": {
    "_id": "contact_id",
    "phone_number": "+11234567890"
  }
}
```

***

### Error (400)

```json JSON
{
  "success": false,
  "message": "Validation error"
}
```

***

## Business Logic Notes

* Contact uniqueness is based on **phone\_number + channel\_id**
* Existing contact fields will be **overwritten** if provided
* Fields not provided will remain unchanged
* Prevents duplicate contact creation

***

## Common Errors

| Error            | Description               |
| ---------------- | ------------------------- |
| Validation error | Missing or invalid fields |
| Unauthorized     | Invalid API key           |
| Invalid channel  | Channel ID does not exist |