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

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 --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": "[phone]",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]"
}'

---

Response

Success (200)

JSON

{
  "success": true,
  "message": "Contact inserted or updated successfully",
  "data": {
    "_id": "contact_id",
    "phone_number": "[phone]"
  }
}

---

Error (400)

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