Skip to main content
POST
/
contacts
/
upsert
Upsert Contact
curl --request POST \
  --url https://services.leadconnectorhq.com/contacts/upsert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Version: <version>' \
  --data '
{
  "locationId": "ve9EPM428h8vShlRW1KT",
  "firstName": "Rosan",
  "lastName": "Deo",
  "name": "Rosan Deo",
  "email": "rosan@deos.com",
  "gender": "male",
  "phone": "+1 888-888-8888",
  "address1": "3535 1st St N",
  "city": "Dolomite",
  "state": "AL",
  "postalCode": "35061",
  "website": "https://www.tesla.com",
  "timezone": "America/Chihuahua",
  "dnd": true,
  "dndSettings": {
    "Call": {
      "status": "active",
      "message": "<string>",
      "code": "<string>"
    },
    "Email": {
      "status": "active",
      "message": "<string>",
      "code": "<string>"
    },
    "SMS": {
      "status": "active",
      "message": "<string>",
      "code": "<string>"
    },
    "WhatsApp": {
      "status": "active",
      "message": "<string>",
      "code": "<string>"
    },
    "GMB": {
      "status": "active",
      "message": "<string>",
      "code": "<string>"
    },
    "FB": {
      "status": "active",
      "message": "<string>",
      "code": "<string>"
    }
  },
  "inboundDndSettings": {
    "all": {
      "status": "active",
      "message": "<string>"
    }
  },
  "tags": [
    "nisi sint commodo amet",
    "consequat"
  ],
  "customFields": [
    {
      "id": "6dvNaf7VhkQ9snc5vnjJ",
      "key": "my_custom_field",
      "field_value": "My Text"
    }
  ],
  "source": "public api",
  "dateOfBirth": "1990-09-25",
  "country": "US",
  "companyName": "DGS VolMAX",
  "assignedTo": "y0BeYjuRIlDwsDcOHOJo",
  "createNewIfDuplicateAllowed": false
}
'
{
  "new": true,
  "contact": {
    "id": "seD4PfOuKoVMLkEZqohJ",
    "name": "rubika deo",
    "locationId": "ve9EPM428h8vShlRW1KT",
    "firstName": "rubika",
    "lastName": "Deo",
    "email": "rubika@deos.com",
    "emailLowerCase": "rubika@deos.com",
    "timezone": "Asia/Calcutta",
    "companyName": "DGS VolMAX",
    "phone": "+18832327657",
    "dnd": true,
    "dndSettings": {
      "Call": {
        "status": "active",
        "message": "<string>",
        "code": "<string>"
      },
      "Email": {
        "status": "active",
        "message": "<string>",
        "code": "<string>"
      },
      "SMS": {
        "status": "active",
        "message": "<string>",
        "code": "<string>"
      },
      "WhatsApp": {
        "status": "active",
        "message": "<string>",
        "code": "<string>"
      },
      "GMB": {
        "status": "active",
        "message": "<string>",
        "code": "<string>"
      },
      "FB": {
        "status": "active",
        "message": "<string>",
        "code": "<string>"
      }
    },
    "type": "read",
    "source": "public api",
    "assignedTo": "ve9EPM428h8vShlRW1KT",
    "address1": "3535 1st St N",
    "city": "ruDolomitebika",
    "state": "AL",
    "country": "US",
    "postalCode": "35061",
    "website": "https://www.tesla.com",
    "tags": [
      "nisi sint commodo amet",
      "consequat"
    ],
    "dateOfBirth": "Date format YYYY-MM-DD",
    "dateAdded": "2021-07-02T05:18:26.704Z",
    "dateUpdated": "2021-07-02T05:18:26.704Z",
    "attachments": "<string>",
    "ssn": "<string>",
    "keyword": "test",
    "firstNameLowerCase": "rubika",
    "fullNameLowerCase": "rubika deo",
    "lastNameLowerCase": "deo",
    "lastActivity": "2021-07-16T11:39:30.564Z",
    "customFields": [
      {
        "id": "MgobCB14YMVKuE4Ka8p1",
        "value": "name"
      }
    ],
    "businessId": "641c094001436dbc2081e642",
    "attributionSource": {
      "url": "Trigger Link",
      "campaign": "<string>",
      "utmSource": "<string>",
      "utmMedium": "<string>",
      "utmContent": "<string>",
      "referrer": "https: //www.google.com",
      "campaignId": "<string>",
      "fbclid": "<string>",
      "gclid": "CjOKCQjwnNyUBhCZARISAI9AYIFtNnIcWcYGIOQINz_ZoFI5SSLRRugSoPZoiEu27IZBY£1-MAIWmEaAo2VEALW_WCB",
      "msclikid": "<string>",
      "dclid": "<string>",
      "fbc": "<string>",
      "fbp": "fb. 1.1674748390986.1171287961",
      "fbEventId": "Mozilla/5.0",
      "userAgent": "Mozilla/5.0",
      "ip": "58.111.106.198",
      "medium": "survey",
      "mediumId": "FglfHAn30PRwsZVyQlKp"
    },
    "lastAttributionSource": {
      "url": "Trigger Link",
      "campaign": "<string>",
      "utmSource": "<string>",
      "utmMedium": "<string>",
      "utmContent": "<string>",
      "referrer": "https: //www.google.com",
      "campaignId": "<string>",
      "fbclid": "<string>",
      "gclid": "CjOKCQjwnNyUBhCZARISAI9AYIFtNnIcWcYGIOQINz_ZoFI5SSLRRugSoPZoiEu27IZBY£1-MAIWmEaAo2VEALW_WCB",
      "msclikid": "<string>",
      "dclid": "<string>",
      "fbc": "<string>",
      "fbp": "fb. 1.1674748390986.1171287961",
      "fbEventId": "Mozilla/5.0",
      "userAgent": "Mozilla/5.0",
      "ip": "58.111.106.198",
      "medium": "survey",
      "mediumId": "FglfHAn30PRwsZVyQlKp"
    },
    "visitorId": "ve9EPM428h8vShlRW1KT"
  },
  "traceId": "<string>"
}

Authorizations

​
Authorization
string
header
required

Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.

Headers

​
Version
enum<string>
required

API Version

Available options:
2021-07-28

Body

application/json
​
locationId
string
required
Example:

"ve9EPM428h8vShlRW1KT"

​
firstName
string | null
Example:

"Rosan"

​
lastName
string | null
Example:

"Deo"

​
name
string | null
Example:

"Rosan Deo"

​
email
string | null
Example:

"rosan@deos.com"

​
gender
string
Example:

"male"

​
phone
string | null
Example:

"+1 888-888-8888"

​
address1
string | null
Example:

"3535 1st St N"

​
city
string | null
Example:

"Dolomite"

​
state
string | null
Example:

"AL"

​
postalCode
string
Example:

"35061"

​
website
string | null
Example:

"https://www.tesla.com"

​
timezone
string | null
Example:

"America/Chihuahua"

​
dnd
boolean
Example:

true

​
dndSettings
object
​
inboundDndSettings
object
​
tags
string[]

This field will overwrite all current tags associated with the contact. To update a tags, it is recommended to use the Add Tag or Remove Tag API instead.

Example:
["nisi sint commodo amet", "consequat"]
​
customFields
object[]
​
source
string
Example:

"public api"

​
dateOfBirth
object

The birth date of the contact. Supported formats: YYYY/MM/DD, MM/DD/YYYY, YYYY-MM-DD, MM-DD-YYYY, YYYY.MM.DD, MM.DD.YYYY, YYYY_MM_DD, MM_DD_YYYY

Example:

"1990-09-25"

​
country
string
Example:

"US"

​
companyName
string | null
Example:

"DGS VolMAX"

​
assignedTo
string

User's Id

Example:

"y0BeYjuRIlDwsDcOHOJo"

​
createNewIfDuplicateAllowed
boolean
default:false

Controls whether to create a new contact or update an existing duplicate. Scenario 1: If this value is true and the location allows duplicate contacts, a new contact will be created immediately without checking for duplicates. Scenario 2: If this value is true but the location does not allow duplicate contacts, this field is ignored and the normal upsert behavior applies: the API will search for an existing duplicate contact, update it if found, or create a new contact if not found. Scenario 3: If this value is false or not provided, the normal upsert behavior applies regardless of the location's duplicate contact setting.

Example:

false

Response

Successful response

​
new
boolean
Example:

true

​
contact
object
​
traceId
string
Last modified on March 4, 2026