Please find the list of acceptable values for the country field here<br/><br/>The Upsert API will adhere to the configuration defined under the “Allow Duplicate Contact” setting at the Account level. If the setting is configured to check both Email and Phone, the API will attempt to identify an existing contact based on the priority sequence specified in the setting, and will create or update the contact accordingly.<br/><br/>If two separate contacts already exist—one with the same email and another with the same phone—and an upsert request includes both the email and phone, the API will update the contact that matches the first field in the configured sequence, and ignore the second field to prevent duplication.

http
POST https://services.leadconnectorhq.com/contacts/upsert

Authorization

NameTypeRequiredExampleDescription
AuthorizationstringYesBearer token generated from the Leadway portal. See Authentication.
VersionstringYes2021-07-28API version.

Body

NameTypeRequiredExampleDescription
firstNamestringNoRosan
lastNamestringNoDeo
namestringNoRosan Deo
emailstringNorosan@deos.com
locationIdstringYesve9EPM428h8vShlRW1KT
genderstringNomale
phonestringNo+1 888-888-8888
address1stringNo3535 1st St N
citystringNoDolomite
statestringNoAL
postalCodestringNo35061
websitestringNohttps://www.tesla.com
timezonestringNoAmerica/Chihuahua
dndbooleanNoTrue
  • dndSettings (object)

    • Call (object)

      • status (string, required): Possible values: 'active', 'inactive', 'permanent'

      • message (string)

      • code (string)

    • Email (object)

      • status (string, required): Possible values: 'active', 'inactive', 'permanent'

      • message (string)

      • code (string)

    • SMS (object)

      • status (string, required): Possible values: 'active', 'inactive', 'permanent'

      • message (string)

      • code (string)

    • WhatsApp (object)

      • status (string, required): Possible values: 'active', 'inactive', 'permanent'

      • message (string)

      • code (string)

    • GMB (object)

      • status (string, required): Possible values: 'active', 'inactive', 'permanent'

      • message (string)

      • code (string)

    • FB (object)

      • status (string, required): Possible values: 'active', 'inactive', 'permanent'

      • message (string)

      • code (string)

  • inboundDndSettings (object)

    • all (object)

      • status (string, required): Possible values: 'active', 'inactive'

      • message (string)

NameTypeRequiredExampleDescription
tagsstring[]NoThis 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.
customFieldsobject[]No
sourcestringNopublic api
dateOfBirthobjectNo1990-09-25The 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
countrystringNoUS
companyNamestringNoDGS VolMAX
assignedTostringNoy0BeYjuRIlDwsDcOHOJoUser's Id
createNewIfDuplicateAllowedbooleanNoFalseControls whether to create a new contact or update an existing duplicate. Scenario 1: If this value is true and the account allows duplicate contacts, a new contact will be created immediately without checking for duplicates. Scenario 2: If this value is true but the account 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 account's duplicate contact setting.

Responses

200 - Successful response
  • new (boolean): Example: True

  • contact (object)

    • id (string): Example: seD4PfOuKoVMLkEZqohJ

    • name (string): Example: rubika deo

    • locationId (string): Example: ve9EPM428h8vShlRW1KT

    • firstName (string): Example: rubika

    • lastName (string): Example: Deo

    • email (string): Example: rubika@deos.com

    • emailLowerCase (string): Example: rubika@deos.com

    • timezone (string): Example: Asia/Calcutta

    • companyName (string): Example: DGS VolMAX

    • phone (string): Example: +18832327657

    • dnd (boolean): Example: True

    • dndSettings (object)

      • Call (object)

        • status (string, required): Possible values: 'active', 'inactive', 'permanent'

        • message (string)

        • code (string)

      • Email (object)

        • status (string, required): Possible values: 'active', 'inactive', 'permanent'

        • message (string)

        • code (string)

      • SMS (object)

        • status (string, required): Possible values: 'active', 'inactive', 'permanent'

        • message (string)

        • code (string)

      • WhatsApp (object)

        • status (string, required): Possible values: 'active', 'inactive', 'permanent'

        • message (string)

        • code (string)

      • GMB (object)

        • status (string, required): Possible values: 'active', 'inactive', 'permanent'

        • message (string)

        • code (string)

      • FB (object)

        • status (string, required): Possible values: 'active', 'inactive', 'permanent'

        • message (string)

        • code (string)

    • type (string): Example: read

    • source (string): Example: public api

    • assignedTo (string): Example: ve9EPM428h8vShlRW1KT

    • address1 (string): Example: 3535 1st St N

    • city (string): Example: ruDolomitebika

    • state (string): Example: AL

    • country (string): Example: US

    • postalCode (string): Example: 35061

    • website (string): Example: https://www.tesla.com

    • tags (string[])

    • dateOfBirth (string): Example: Date format YYYY-MM-DD

    • dateAdded (string): Example: 2021-07-02T05:18:26.704Z

    • dateUpdated (string): Example: 2021-07-02T05:18:26.704Z

    • attachments (string)

    • ssn (string)

    • keyword (string): Example: test

    • firstNameLowerCase (string): Example: rubika

    • fullNameLowerCase (string): Example: rubika deo

    • lastNameLowerCase (string): Example: deo

    • lastActivity (string): Example: 2021-07-16T11:39:30.564Z

    • customFields (object[])

      • id (string): Example: MgobCB14YMVKuE4Ka8p1

      • value (string): Example: name

    • businessId (string): Example: 641c094001436dbc2081e642

    • attributionSource (object)

      • url (string, required): Example: Trigger Link

      • campaign (string)

      • utmSource (string)

      • utmMedium (string)

      • utmContent (string)

      • referrer (string): Example: https: //www.google.com

      • campaignId (string)

      • fbclid (string)

      • gclid (string): Example: CjOKCQjwnNyUBhCZARISAI9AYIFtNnIcWcYGIOQINz_ZoFI5SSLRRugSoPZoiEu27IZBY£1-MAIWmEaAo2VEALW_WCB

      • msclikid (string)

      • dclid (string)

      • fbc (string)

      • fbp (string): Example: fb. 1.1674748390986.1171287961

      • fbEventId (string): Example: Mozilla/5.0

      • userAgent (string): Example: Mozilla/5.0

      • ip (string): Example: 58.111.106.198

      • medium (string): Example: survey

      • mediumId (string): Example: FglfHAn30PRwsZVyQlKp

    • lastAttributionSource (object)

      • url (string, required): Example: Trigger Link

      • campaign (string)

      • utmSource (string)

      • utmMedium (string)

      • utmContent (string)

      • referrer (string): Example: https: //www.google.com

      • campaignId (string)

      • fbclid (string)

      • gclid (string): Example: CjOKCQjwnNyUBhCZARISAI9AYIFtNnIcWcYGIOQINz_ZoFI5SSLRRugSoPZoiEu27IZBY£1-MAIWmEaAo2VEALW_WCB

      • msclikid (string)

      • dclid (string)

      • fbc (string)

      • fbp (string): Example: fb. 1.1674748390986.1171287961

      • fbEventId (string): Example: Mozilla/5.0

      • userAgent (string): Example: Mozilla/5.0

      • ip (string): Example: 58.111.106.198

      • medium (string): Example: survey

      • mediumId (string): Example: FglfHAn30PRwsZVyQlKp

    • visitorId (string): visitorId is the Unique ID assigned to each Live chat visitor. Example: ve9EPM428h8vShlRW1KT

  • traceId (string)

json
{
  "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"
  // truncado: 81 lineas mas
}
400 - Bad Request
json
{}
401 - Unauthorized
json
{}
422 - Unprocessable Entity
json
{}

Example

curl -X POST 'https://services.leadconnectorhq.com/contacts/upsert' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Version: 2021-07-28' \
  -H 'Content-Type: application/json' \
  -d '{
  "firstName": "Rosan",
  "lastName": "Deo",
  "name": "Rosan Deo",
  "email": "rosan@deos.com",
  "locationId": "ve9EPM428h8vShlRW1KT",
  "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": [],
  "source": "public api",
  "dateOfBirth": "1990-09-25",
  "country": "US",
  "companyName": "DGS VolMAX",
  "assignedTo": "y0BeYjuRIlDwsDcOHOJo",
  "createNewIfDuplicateAllowed": false
}'

Last updated October 26, 2026

Was this page helpful?